Skip to main content

​
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.
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.

​
The two deployment shapes

Local npx + local ComfyUI

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.

Local npx + dockerized / remote ComfyUI

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.

​
Example: ComfyUI in docker-compose

A ready-to-use example lives in the repo at 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:
Then point your MCP client at the container. On the host (the common case — Claude Code on the same machine), use the published port:
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:
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 is a ComfyUI extension, not a service, and is optional when an external front end is your surface.
  • docker/runpod/ in this repo is a CUDA-oriented RunPod cloud image (see Cloud deployment), not a general-purpose ComfyUI image — AMD users should not start there.