comfyui-mcp

MCP server exposing a local (or LAN) ComfyUI instance's HTTP API as tools, so an LLM client (Claude Desktop, Claude Code, etc.) can queue generations, inspect the queue/history, upload reference images, browse installed models/nodes, and pull back generated images -- without hand-rolling curl calls every time.

Built with Python + FastMCP, stdio transport (local subprocess, talks to ComfyUI over HTTP on 127.0.0.1:8188 by default).

Requirements

• Python 3.10+

• A running ComfyUI instance reachable over HTTP (default assumes the same machine, default port)

Related MCP server: ComfyUI MCP

Install

cd comfyui-mcp   # this directory
python -m venv .venv
.venv\Scripts\activate        # Windows
# source .venv/bin/activate   # macOS/Linux
pip install -r requirements.txt

Configure

Environment variables (optional -- sane defaults for a local install):

The last three power the filesystem-backed tools. They assume the MCP server process runs on the same (Windows) host as ComfyUI, which is the intended setup.

Copy .env.example to .env and edit if your ComfyUI runs on a different host/port, or just set the variables in your MCP client config (see below).

Register with an MCP client

Claude Code:

claude mcp add comfyui -- python /absolute/path/to/comfyui-mcp/comfyui_mcp/server.py

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "comfyui": {
      "command": "python",
      "args": ["/absolute/path/to/comfyui-mcp/comfyui_mcp/server.py"],
      "env": {
        "COMFYUI_BASE_URL": "http://127.0.0.1:8188"
      }
    }
  }
}

Use the venv's Python interpreter path (.venv/Scripts/python.exe on Windows, .venv/bin/python on macOS/Linux) if you don't want to rely on a global install.

Tools

Design notes

• Endpoint shapes were verified against ComfyUI's actual server.py (fetched from comfyanonymous/ComfyUI master), not assumed, since the API has no formal versioned spec.

• Images are references, not inline bytes, by default. comfyui_generate_image and comfyui_get_history return {filename, subfolder, type} for each output image; call comfyui_view_image to actually fetch and view one. This keeps responses small when a batch produces several images, most of which the agent won't need to inspect.

• Large ComfyUI payloads are summarized by default. /object_info (all node schemas) and /queue//history (which embed full node graphs) can be tens to hundreds of KB. comfyui_get_queue, comfyui_get_history, and comfyui_get_node_info default to condensed output with a summary=false / explicit node_class escape hatch for full detail.

• wait + polling for completion; websocket for progress. Job completion is detected by polling /history/{prompt_id} (it only populates once a job finishes) up to a per-call timeout — this maps cleanly onto a synchronous tool call, and wait=false returns immediately with a prompt_id to check later via comfyui_get_history. Live progress (node/step/percent) can't be polled from /history, so a single background subscription to ComfyUI's /ws websocket caches the latest progress per prompt_id, surfaced by comfyui_get_progress. The websocket is best-effort: if it can't connect (or websockets isn't installed), progress reports "unknown" and nothing else breaks.

• The filesystem bridge (comfyui_save_output, comfyui_get_lora_metadata). These are the only tools that touch the host filesystem. ComfyUI's output/ dir isn't visible to the client's sandbox, and its API exposes LoRA names but not their on-disk paths — so both tools read/write local paths directly. Every access is confined to a configured root (COMFYUI_MOUNT_DIR / COMFYUI_LORA_DIR) and validated against directory traversal. comfyui_save_output fetches bytes through the existing /view endpoint rather than reading ComfyUI's output dir directly, so it works without knowing where ComfyUI stores files.

• Server-side workflow templates. comfyui_run_template renders a stored API graph (comfyui_mcp/templates/*.json) by substituting typed slots — "{{seed}}" as a whole value keeps its int/bool/null type; "{{x}}" inside a longer string is spliced as text. A graph that references an undeclared slot is rejected before submission, rather than shipping a literal {{typo}}. Add your own canonical graphs (Krea2 base, film-grain tail, caption stack) as new files in that directory.

• No response_format (json/markdown) toggle. Every tool returns plain JSON. For a single-user local tool this is simpler and more predictable than maintaining two output shapes per tool; revisit if this ever needs to serve a chat-facing UI that benefits from markdown.

• Newer /api/jobs endpoint intentionally not used. ComfyUI's current master branch has a richer job-status API (/api/jobs/{id} with explicit pending/in_progress/completed/failed status), but it's very recent and may not exist on older ComfyUI installs. /history + /queue are long-standing and work everywhere, so they're used for polling instead. Worth revisiting if you're always running latest ComfyUI.

Testing

Run the unit tests:

.venv\Scripts\python.exe -m pytest tests/ -q

They cover the pure logic in the newer tools without needing a live ComfyUI: the safetensors metadata reader, template loading + slot substitution (including type preservation and undeclared-slot rejection), path-traversal safety, the http→ws URL derivation, the progress tracker's websocket-message handling, the prompt/slots JSON-string coercion, and image downscaling. All 20 tools also register cleanly with FastMCP.

Exercise the filesystem/networked tools against a real ComfyUI instance before relying on them — checkpoint/sampler/scheduler names are install-specific (use comfyui_list_models and comfyui_get_node_info(node_class="KSampler")), and comfyui_save_output / comfyui_get_lora_metadata depend on the COMFYUI_MOUNT_DIR / COMFYUI_LORA_DIR paths being correct for your machine.