> ## Documentation Index
> Fetch the complete documentation index at: https://comfyui-mcp.artokun.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Docker & Compose

> Run ComfyUI as a docker-compose service and connect comfyui-mcp to it — and why comfyui-mcp itself is never a compose service.

## comfyui-mcp is stdio — it cannot be a compose service

`comfyui-mcp` is a **stdio MCP server**. It has no port and exposes nothing
over the network: the MCP client (Claude Code, Cursor, an MCP bridge, …)
**spawns it as a child process** and talks to it over stdin/stdout.

So in a `docker-compose.yml`, a `comfyui-mcp` service is a dead end — it would
start, have no one to talk to, and exit. This trips up almost everyone wiring
ComfyUI into compose, because a correct compose file looks like it's "missing"
a service. It isn't: what you compose is **ComfyUI**, and the MCP server runs
wherever your MCP client runs, reaching ComfyUI over plain HTTP via
`COMFYUI_URL`.

<Note>
  The `npx` command that launches the server requires **Node.js >= 22** on the
  machine (or container) that runs it — the main gotcha for slim base images.
</Note>

## The two deployment shapes

<CardGroup cols={2}>
  <Card title="Local npx + local ComfyUI" icon="laptop">
    The default. ComfyUI runs directly on your machine; the MCP client spawns
    `npx -y comfyui-mcp@latest`, which auto-detects the local install and its
    port. No config needed. See [Installation](./installation).
  </Card>

  <Card title="Local npx + dockerized / remote ComfyUI" icon="docker">
    ComfyUI runs in a container (or on another host); the MCP client still
    spawns `comfyui-mcp` locally, pointed at it with `COMFYUI_URL` (or
    `--comfyui-url`). A non-loopback URL puts the server in **remote mode**:
    all HTTP tools work, and local-only tools (installing custom nodes,
    reading logs, removing model files) return a clear error.
  </Card>
</CardGroup>

## Example: ComfyUI in docker-compose

A ready-to-use example lives in the repo at
[`docker/compose/`](https://github.com/artokun/comfyui-mcp/tree/main/docker/compose)
— ComfyUI as a service (NVIDIA default, AMD/ROCm variant commented in), bind
mounts for models and outputs, and the client config in the header comments:

```yaml theme={null}
services:
  comfyui:
    image: yanwk/comfyui-boot:cu130-slim-v2   # community image; :rocm for AMD
    ports:
      - "8188:8188"
    volumes:
      - ./storage/models:/root/ComfyUI/models
      - ./storage/custom_nodes:/root/ComfyUI/custom_nodes
      - ./storage/input:/root/ComfyUI/input
      - ./storage/output:/root/ComfyUI/output
      - ./storage/user:/root/ComfyUI/user
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]
```

Then point your MCP client at the container. On the **host** (the common case —
Claude Code on the same machine), use the published port:

```json theme={null}
{
  "mcpServers": {
    "comfyui": {
      "command": "npx",
      "args": ["-y", "comfyui-mcp@latest"],
      "env": {
        "COMFYUI_URL": "http://localhost:8188"
      }
    }
  }
}
```

If the MCP client runs **inside another compose service** on the same network
(e.g. an MCP-to-HTTP bridge fronting Open WebUI), use the **compose service
name**, not `localhost`:

```
COMFYUI_URL=http://comfyui:8188
```

In that layout the bridge service is what spawns `comfyui-mcp`, so its image
must contain Node.js >= 22 with the server launchable via
`npx -y comfyui-mcp@latest`. Bridges are third-party software — configure
yours per its own docs; the example compose file has a commented sketch.

## AMD / ROCm notes

* Use the `yanwk/comfyui-boot:rocm` image tag and uncomment the ROCm
  passthrough in the example — the bits people miss:
  `devices: [/dev/kfd, /dev/dri]`, `group_add: [video]`,
  `security_opt: [seccomp:unconfined]`.
* `comfyui-mcp` itself has **no GPU/CUDA dependency** — ROCm hosts are fully
  supported. The [Agent Panel](./panel) is a **ComfyUI extension**, not a
  service, and is optional when an external front end is your surface.
* [`docker/runpod/`](https://github.com/artokun/comfyui-mcp/tree/main/docker/runpod)
  in this repo is a **CUDA-oriented RunPod cloud image** (see
  [Cloud deployment](./cloud-deployment)), not a general-purpose ComfyUI image —
  AMD users should not start there.