mcp-comfyui

MCP server bridging Claude Desktop to local and remote ComfyUI instances, including Comfy Cloud.

Tools

Requirements

• Python 3.11+

• Local ComfyUI instance or a Comfy Cloud subscription

Install

pip install -r requirements.txt

Configuration

Server config format

Each entry in COMFYUI_SERVERS is either a plain URL string (local, no auth) or a dict:

{
  // String shorthand — local ComfyUI, no auth
  "default": "http://localhost:8188",

  // Dict — full options
  "remote": { "url": "http://192.168.1.100:8188", "mode": "local" },
  "cloud":  { "url": "https://cloud.comfy.org", "api_key": "YOUR_KEY", "mode": "cloud" }
}

mode is "local" (default) or "cloud". api_key is required for Comfy Cloud.

If COMFYUI_SERVERS is absent, defaults to {"default": "http://localhost:8000"}.

Via .env file

cp .env.example .env
# edit .env

Via Claude Desktop config

~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "comfyui": {
      "command": "/opt/miniconda3/bin/python3",
      "args": ["/path/to/mcp-comfyui/server.py"],
      "env": {
        "COMFYUI_SERVERS": "{\"default\": \"http://localhost:8188\", \"cloud\": {\"url\": \"https://cloud.comfy.org\", \"api_key\": \"YOUR_KEY\", \"mode\": \"cloud\"}}"
      }
    }
  }
}

Omit env to use .env file instead.

Typical Workflow

1. comfyui_health — confirm server up

2. comfyui_list_models — find available checkpoints/LoRAs

3. comfyui_queue_prompt — submit workflow JSON, get prompt_id

4. comfyui_poll_status — repeat until status = completed

5. comfyui_get_outputs — get file paths (local) or /api/view download URLs (cloud)

Mode Differences

Manual Test

/opt/miniconda3/bin/python3 -c "
import asyncio
from server import comfyui_health, comfyui_list_models, ServerInput, ListModelsInput

async def main():
    print(await comfyui_health(ServerInput(server='default')))
    print(await comfyui_list_models(ListModelsInput(server='default', filter='checkpoints')))

asyncio.run(main())
"

Notes

• comfyui_queue_prompt expects valid ComfyUI API-format workflow JSON. No validation performed.

• Local output paths built from --output-directory flag reported in /system_stats.

• Cloud outputs: caller must follow the 302 redirect from /api/view to reach the signed storage URL.

• Stdio transport only — this server opens no network ports.