mcp-comfyui

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

Tools

Tool	Description
comfyui_health	Check server reachable + response time
comfyui_list_models	List models by type (checkpoints, loras, etc.)
comfyui_queue_prompt	Queue a workflow, get prompt ID back immediately
comfyui_poll_status	Poll prompt status (queued / running / completed / error / cancelled)
comfyui_get_outputs	Get output file paths or download URLs after completion

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

Behaviour	Local	Cloud
Health probe	GET /system_stats	GET /api/queue
Auth	none	X-API-Key header
Submit workflow	POST /api/prompt	POST /api/prompt
Poll status	/history/{id} + /queue	/api/job/{id}/status
Status values	queued / running / completed / error	+ cancelled
Outputs	absolute filesystem paths	/api/view?filename=… URLs (302 → signed URL)
Model listing	/api/models/{type} → /api/object_info fallback	same

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.