ComfyUI MCP

简体中文

A universal Model Context Protocol server that lets MCP-capable agents discover ComfyUI nodes, build and edit API workflows, run them, inspect the queue, retrieve outputs, and optionally render the generated graph on an open ComfyUI canvas.

The core is agent-neutral. This repository also packages that same server and one portable Agent Skill for Codex, Claude Code, Gemini CLI, Cursor, and GitHub Copilot CLI. The host adapters contain only manifests and launch configuration; no agent gets a forked implementation.

Project status: alpha. The core workflow store, graph editing, validation, execution, and canvas bridge are implemented. Test against a non-production ComfyUI installation before giving an agent access to valuable models, paid nodes, or a shared GPU queue.

Agent plugins and built-in skill

The repository now includes skills/comfyui-workflow/SKILL.md. It teaches compatible agents how to discover the live node schema, edit revisioned graphs, validate before execution, handle queue and file operations safely, and report generated outputs. This is what makes an installed agent know how to combine the MCP tools instead of seeing only a flat tool list.

All adapters share the same Python server and skill. They use uv to start the bundled source, so uv must be on PATH; the first launch may need to download Python dependencies. See docs/agent-integrations.md for persistent install commands, non-default ComfyUI URLs, explicit skill invocation, verification, and packaging details.

Related MCP server: ComfyPilot

What it does

• Discovers installed core and custom node types through ComfyUI's live /object_info schema.

• Searches model folders and workflow templates without putting huge responses in agent context.

• Imports, creates, versions, and edits ComfyUI API-format workflows.

• Adds and removes nodes, sets literal inputs, and connects or disconnects graph edges.

• Performs local graph checks and live validation against the connected ComfyUI instance.

• Submits workflows, applies one-run-only overrides, inspects queue/history, and interrupts jobs.

• Uploads allowed input images and downloads generated files to a managed output directory.

• Optionally mirrors an API workflow onto every open ComfyUI canvas through the bundled bridge.

• Supports local stdio, Streamable HTTP, and legacy SSE MCP transports.

Architecture

MCP client (Codex, Claude, Cursor, custom agent, ...)
                         │
                         │ stdio / Streamable HTTP
                         ▼
                comfyui-mcp-server
             ┌───────────┴───────────┐
             │ workflow store/editor │
             │ typed MCP tools       │
             │ ComfyUI HTTP client   │
             └───────────┬───────────┘
                         │
             ComfyUI HTTP API / WebSocket
                         │
             ┌───────────┴────────────┐
             │ execution backend     │
             │ optional canvas bridge│
             └────────────────────────┘

The execution backend and visual canvas are intentionally separate:

• ComfyUI's /prompt endpoint accepts an API-format workflow and executes it headlessly.

• An API submission does not modify an already open browser canvas.

• The optional comfyui_extension receives the same API workflow and reconstructs visible nodes, widgets, and links on the canvas. Execution still uses the standard ComfyUI API.

See docs/architecture.md for the design and trust boundaries.

Requirements

• Python 3.11 or newer.

• A reachable local or remote ComfyUI server.

• An MCP client with stdio, Streamable HTTP, or SSE support.

• uv for the bundled agent-plugin launchers. It remains optional when the Python package is installed manually and a generic MCP client launches comfyui-mcp directly.

ComfyUI defaults to http://127.0.0.1:8188, which is also this project's default.

Install from this repository

git clone https://github.com/yutianxiao6/comfyui-mcp.git
cd comfyui-mcp
uv sync
uv run comfyui-mcp --version

With regular Python tooling:

python -m venv .venv
source .venv/bin/activate
pip install -e .
comfyui-mcp --version

After the package is published, clients will also be able to launch it with a command such as:

uvx --from comfyui-mcp-server comfyui-mcp

Start the server

Local stdio

stdio is the safest and most widely supported mode. The MCP client starts one private server process:

COMFYUI_URL=http://127.0.0.1:8188 uv run comfyui-mcp

Streamable HTTP

Use this when several clients need the same MCP endpoint:

uv run comfyui-mcp --transport streamable-http --host 127.0.0.1 --port 8000

Clients connect to http://127.0.0.1:8000/mcp.

The server refuses non-loopback binding by default because its tools can execute GPU workloads, read configured input files, and control the ComfyUI queue. If remote access is required, place it behind TLS and authentication, then explicitly set COMFYUI_MCP_ALLOW_REMOTE=true. See SECURITY.md.

Connect an MCP client

Most desktop and IDE clients accept the same mcpServers shape. Replace the repository path:

{
  "mcpServers": {
    "comfyui": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/comfyui-mcp",
        "comfyui-mcp"
      ],
      "env": {
        "COMFYUI_URL": "http://127.0.0.1:8188"
      }
    }
  }
}

The exact file or settings screen differs between MCP clients, but the command, arguments, environment variables, and protocol are not vendor-specific. A copyable example is available at examples/mcp-client-config.example.json.

For an already running Streamable HTTP server, configure the client with:

http://127.0.0.1:8000/mcp

Suggested agent workflow

A reliable agent should use the tools in this order:

1. Call comfyui_health.

2. Search with comfyui_list_node_types, then inspect exact schemas with comfyui_get_node_type.

3. Create or import an API workflow.

4. Add nodes, set inputs, and connect outputs by zero-based index.

5. Call comfyui_validate_workflow.

6. Optionally call comfyui_sync_canvas so a person can inspect the graph.

7. Call comfyui_run_workflow only after execution has been requested.

8. Poll comfyui_get_run, then download selected outputs.

Example user request:

Import my SDXL API workflow as portrait-v1. Replace its checkpoint, add a
ControlNet branch, validate it, show it on the ComfyUI canvas, and run one copy
with seed 42.

MCP tools

Mutating workflow tools accept expected_revision. Agents should pass the revision returned by the previous tool when concurrent edits are possible. A stale edit fails instead of silently overwriting newer work.

Workflow format

The store uses ComfyUI's API format: node IDs are object keys, class_type identifies the node, and a connection is [source_node_id, zero_based_output_index].

{
  "4": {
    "class_type": "CheckpointLoaderSimple",
    "inputs": { "ckpt_name": "model.safetensors" }
  },
  "6": {
    "class_type": "CLIPTextEncode",
    "inputs": {
      "text": "a cinematic portrait",
      "clip": ["4", 1]
    }
  }
}

The normal visual workflow JSON contains nodes and links and is not the same format. In ComfyUI, use Save (API Format) before importing. The server detects visual workflow documents and returns a specific error instead of storing an unusable graph.

Managed records are saved under:

<data-dir>/workflows/<name>.json
<data-dir>/outputs/<prompt-id>/<filename>

The default data directory follows the operating system's user data convention. Override it with COMFYUI_MCP_DATA_DIR.

Optional visual canvas bridge

Install the bridge from either a source checkout or a published package:

uv run comfyui-mcp --install-canvas-bridge /absolute/path/to/ComfyUI

The installer refuses to overwrite an existing bridge directory. During source development, you can instead symlink comfyui_extension into the ComfyUI custom-node directory:

ln -s /absolute/path/to/comfyui-mcp/comfyui_extension \
  /absolute/path/to/ComfyUI/custom_nodes/comfyui_mcp_bridge

Restart ComfyUI and refresh its browser page. comfyui_health should then report canvas_bridge.installed: true.

Local loopback calls need no token. Docker, LAN, and remote deployments must configure the same random token in both processes:

# ComfyUI process
COMFYUI_MCP_BRIDGE_TOKEN="replace-with-a-long-random-value" python main.py

# MCP server process
COMFYUI_MCP_BRIDGE_TOKEN="replace-with-a-long-random-value" uv run comfyui-mcp

Current bridge behavior:

• replace clears the canvas before reconstructing the API graph.

• merge adds the reconstructed graph to the existing canvas.

• Nodes receive a deterministic layered layout because API-format workflows do not contain visual positions.

• Unknown custom nodes and unresolved links are reported as canvas warnings.

• The event is broadcast to open ComfyUI browser sessions connected to that server.

Canvas synchronization is a convenience and review surface, not the source of truth. The managed API workflow is what gets executed.

Configuration

Example allowing two upload directories on Linux/macOS:

COMFYUI_MCP_INPUT_ROOTS="/data/comfy-inputs:/home/me/reference-images" uv run comfyui-mcp

Use ; instead of : on Windows.

Local ComfyUI and Comfy Cloud

The implementation targets the stable local ComfyUI routes by default. A Comfy Cloud-compatible deployment can use COMFYUI_API_PREFIX=/api and COMFYUI_API_KEY; cloud endpoint behavior and available features may differ. The canvas bridge is intended for a ComfyUI instance where the bundled custom extension can be installed.

Do not expose an unauthenticated local ComfyUI port directly to the internet. Put remote ComfyUI behind an authenticated reverse proxy or a private network.

Development

uv sync --extra dev
uv run pytest
uv run ruff check .
uv run ruff format --check .

Run the MCP Inspector against stdio:

uv run mcp dev src/comfyui_mcp/dev_server.py:mcp

Or start Streamable HTTP and connect the Inspector to http://127.0.0.1:8000/mcp:

uv run comfyui-mcp --transport streamable-http
npx -y @modelcontextprotocol/inspector

Known limitations

• Import currently accepts API-format workflows, not automatic conversion from arbitrary visual workflow JSON.

• The bridge reconstructs a practical graph layout; it cannot recover original groups, comments, colors, or positions that are absent from API format.

• Live progress is available from ComfyUI itself, while the current MCP API exposes pollable run status rather than a long-running streaming tool call.

• Some custom nodes rely on browser-only state and cannot run correctly in ComfyUI API mode.

• Streamable HTTP authentication must currently be supplied by a trusted reverse proxy.

Roadmap

• Bidirectional canvas editing and explicit visual-workflow import/export.

• WebSocket-backed progress notifications and preview resources.

• Workflow transactions for multi-edit atomic changes.

• Safer policy profiles for paid nodes, model allowlists, and maximum image dimensions.

• Packaging the canvas bridge for the ComfyUI Registry.

• Compatibility fixtures for major MCP hosts and ComfyUI releases.

Contributing

Issues and pull requests are welcome. Read CONTRIBUTING.md and SECURITY.md before publishing a change or vulnerability report.

License

Apache License 2.0. See LICENSE.