{
  "markdown": "# ComfyUI MCP\n\n[简体中文](README.zh-CN.md)\n\nA universal [Model Context Protocol](https://modelcontextprotocol.io/) server that lets MCP-capable\nagents discover ComfyUI nodes, build and edit API workflows, run them, inspect the queue, retrieve\noutputs, and optionally render the generated graph on an open ComfyUI canvas.\n\nThe core is agent-neutral. This repository also packages that same server and one portable Agent\nSkill for Codex, Claude Code, Gemini CLI, Cursor, and GitHub Copilot CLI. The host adapters contain\nonly manifests and launch configuration; no agent gets a forked implementation.\n\n> **Project status:** alpha. The core workflow store, graph editing, validation, execution, and\n> canvas bridge are implemented. Test against a non-production ComfyUI installation before giving\n> an agent access to valuable models, paid nodes, or a shared GPU queue.\n\n## Agent plugins and built-in skill\n\nThe repository now includes `skills/comfyui-workflow/SKILL.md`. It teaches compatible agents how to\ndiscover the live node schema, edit revisioned graphs, validate before execution, handle queue and\nfile operations safely, and report generated outputs. This is what makes an installed agent know\n*how* to combine the MCP tools instead of seeing only a flat tool list.\n\n| Host | Included adapter | Local install or test |\n| --- | --- | --- |\n| Codex | `.codex-plugin/plugin.json` | `codex plugin marketplace add yutianxiao6/comfyui-mcp`, then `codex plugin add comfyui-mcp@comfyui-mcp` |\n| Claude Code | `.claude-plugin/plugin.json` | `claude --plugin-dir /absolute/path/to/comfyui-mcp` |\n| Gemini CLI | `gemini-extension.json` | `gemini extensions link /absolute/path/to/comfyui-mcp` |\n| Cursor | `.cursor-plugin/plugin.json` | Link or copy into `~/.cursor/plugins/local/comfyui-mcp` |\n| GitHub Copilot CLI | `.plugin/plugin.json` | `copilot plugins install /absolute/path/to/comfyui-mcp` |\n| Other MCP clients | Generic example | Register `examples/mcp-client-config.example.json` |\n\nAll adapters share the same Python server and skill. They use `uv` to start the bundled source, so\n`uv` must be on `PATH`; the first launch may need to download Python dependencies. See\n[docs/agent-integrations.md](docs/agent-integrations.md) for persistent install commands,\nnon-default ComfyUI URLs, explicit skill invocation, verification, and packaging details.\n\n## What it does\n\n- Discovers installed core and custom node types through ComfyUI's live `/object_info` schema.\n- Searches model folders and workflow templates without putting huge responses in agent context.\n- Imports, creates, versions, and edits ComfyUI API-format workflows.\n- Adds and removes nodes, sets literal inputs, and connects or disconnects graph edges.\n- Performs local graph checks and live validation against the connected ComfyUI instance.\n- Submits workflows, applies one-run-only overrides, inspects queue/history, and interrupts jobs.\n- Uploads allowed input images and downloads generated files to a managed output directory.\n- Optionally mirrors an API workflow onto every open ComfyUI canvas through the bundled bridge.\n- Supports local `stdio`, Streamable HTTP, and legacy SSE MCP transports.\n\n## Architecture\n\n```text\nMCP client (Codex, Claude, Cursor, custom agent, ...)\n                         │\n                         │ stdio / Streamable HTTP\n                         ▼\n                comfyui-mcp-server\n             ┌───────────┴───────────┐\n             │ workflow store/editor │\n             │ typed MCP tools       │\n             │ ComfyUI HTTP client   │\n             └───────────┬───────────┘\n                         │\n             ComfyUI HTTP API / WebSocket\n                         │\n             ┌───────────┴────────────┐\n             │ execution backend     │\n             │ optional canvas bridge│\n             └────────────────────────┘\n```\n\nThe execution backend and visual canvas are intentionally separate:\n\n- ComfyUI's `/prompt` endpoint accepts an **API-format workflow** and executes it headlessly.\n- An API submission does not modify an already open browser canvas.\n- The optional `comfyui_extension` receives the same API workflow and reconstructs visible nodes,\n  widgets, and links on the canvas. Execution still uses the standard ComfyUI API.\n\nSee [docs/architecture.md](docs/architecture.md) for the design and trust boundaries.\n\n## Requirements\n\n- Python 3.11 or newer.\n- A reachable local or remote ComfyUI server.\n- An MCP client with `stdio`, Streamable HTTP, or SSE support.\n- `uv` for the bundled agent-plugin launchers. It remains optional when the Python package is\n  installed manually and a generic MCP client launches `comfyui-mcp` directly.\n\nComfyUI defaults to `http://127.0.0.1:8188`, which is also this project's default.\n\n## Install from this repository\n\n```bash\ngit clone https://github.com/yutianxiao6/comfyui-mcp.git\ncd comfyui-mcp\nuv sync\nuv run comfyui-mcp --version\n```\n\nWith regular Python tooling:\n\n```bash\npython -m venv .venv\nsource .venv/bin/activate\npip install -e .\ncomfyui-mcp --version\n```\n\nAfter the package is published, clients will also be able to launch it with a command such as:\n\n```bash\nuvx --from comfyui-mcp-server comfyui-mcp\n```\n\n## Start the server\n\n### Local stdio\n\n`stdio` is the safest and most widely supported mode. The MCP client starts one private server\nprocess:\n\n```bash\nCOMFYUI_URL=http://127.0.0.1:8188 uv run comfyui-mcp\n```\n\n### Streamable HTTP\n\nUse this when several clients need the same MCP endpoint:\n\n```bash\nuv run comfyui-mcp --transport streamable-http --host 127.0.0.1 --port 8000\n```\n\nClients connect to `http://127.0.0.1:8000/mcp`.\n\nThe server refuses non-loopback binding by default because its tools can execute GPU workloads,\nread configured input files, and control the ComfyUI queue. If remote access is required, place it\nbehind TLS and authentication, then explicitly set `COMFYUI_MCP_ALLOW_REMOTE=true`. See\n[SECURITY.md](SECURITY.md).\n\n## Connect an MCP client\n\nMost desktop and IDE clients accept the same `mcpServers` shape. Replace the repository path:\n\n```json\n{\n  \"mcpServers\": {\n    \"comfyui\": {\n      \"command\": \"uv\",\n      \"args\": [\n        \"run\",\n        \"--directory\",\n        \"/absolute/path/to/comfyui-mcp\",\n        \"comfyui-mcp\"\n      ],\n      \"env\": {\n        \"COMFYUI_URL\": \"http://127.0.0.1:8188\"\n      }\n    }\n  }\n}\n```\n\nThe exact file or settings screen differs between MCP clients, but the command, arguments,\nenvironment variables, and protocol are not vendor-specific. A copyable example is available at\n[examples/mcp-client-config.example.json](examples/mcp-client-config.example.json).\n\nFor an already running Streamable HTTP server, configure the client with:\n\n```text\nhttp://127.0.0.1:8000/mcp\n```\n\n## Suggested agent workflow\n\nA reliable agent should use the tools in this order:\n\n1. Call `comfyui_health`.\n2. Search with `comfyui_list_node_types`, then inspect exact schemas with\n   `comfyui_get_node_type`.\n3. Create or import an API workflow.\n4. Add nodes, set inputs, and connect outputs by zero-based index.\n5. Call `comfyui_validate_workflow`.\n6. Optionally call `comfyui_sync_canvas` so a person can inspect the graph.\n7. Call `comfyui_run_workflow` only after execution has been requested.\n8. Poll `comfyui_get_run`, then download selected outputs.\n\nExample user request:\n\n```text\nImport my SDXL API workflow as portrait-v1. Replace its checkpoint, add a\nControlNet branch, validate it, show it on the ComfyUI canvas, and run one copy\nwith seed 42.\n```\n\n## MCP tools\n\n| Area | Tools |\n| --- | --- |\n| Connection | `comfyui_health` |\n| Discovery | `comfyui_list_node_types`, `comfyui_get_node_type`, `comfyui_list_models`, `comfyui_list_templates` |\n| Workflow store | `comfyui_list_workflows`, `comfyui_create_workflow`, `comfyui_import_workflow`, `comfyui_get_workflow` |\n| Graph editing | `comfyui_add_node`, `comfyui_remove_node`, `comfyui_set_input`, `comfyui_connect_nodes`, `comfyui_disconnect_input` |\n| Validation and canvas | `comfyui_validate_workflow`, `comfyui_sync_canvas` |\n| Execution | `comfyui_run_workflow`, `comfyui_get_run`, `comfyui_get_queue`, `comfyui_interrupt`, `comfyui_clear_queue` |\n| Files | `comfyui_upload_image`, `comfyui_download_output` |\n\nMutating workflow tools accept `expected_revision`. Agents should pass the revision returned by the\nprevious tool when concurrent edits are possible. A stale edit fails instead of silently\noverwriting newer work.\n\n## Workflow format\n\nThe store uses ComfyUI's API format: node IDs are object keys, `class_type` identifies the node,\nand a connection is `[source_node_id, zero_based_output_index]`.\n\n```json\n{\n  \"4\": {\n    \"class_type\": \"CheckpointLoaderSimple\",\n    \"inputs\": { \"ckpt_name\": \"model.safetensors\" }\n  },\n  \"6\": {\n    \"class_type\": \"CLIPTextEncode\",\n    \"inputs\": {\n      \"text\": \"a cinematic portrait\",\n      \"clip\": [\"4\", 1]\n    }\n  }\n}\n```\n\nThe normal visual workflow JSON contains `nodes` and `links` and is not the same format. In\nComfyUI, use **Save (API Format)** before importing. The server detects visual workflow documents\nand returns a specific error instead of storing an unusable graph.\n\nManaged records are saved under:\n\n```text\n<data-dir>/workflows/<name>.json\n<data-dir>/outputs/<prompt-id>/<filename>\n```\n\nThe default data directory follows the operating system's user data convention. Override it with\n`COMFYUI_MCP_DATA_DIR`.\n\n## Optional visual canvas bridge\n\nInstall the bridge from either a source checkout or a published package:\n\n```bash\nuv run comfyui-mcp --install-canvas-bridge /absolute/path/to/ComfyUI\n```\n\nThe installer refuses to overwrite an existing bridge directory. During source development, you\ncan instead symlink `comfyui_extension` into the ComfyUI custom-node directory:\n\n```bash\nln -s /absolute/path/to/comfyui-mcp/comfyui_extension \\\n  /absolute/path/to/ComfyUI/custom_nodes/comfyui_mcp_bridge\n```\n\nRestart ComfyUI and refresh its browser page. `comfyui_health` should then report\n`canvas_bridge.installed: true`.\n\nLocal loopback calls need no token. Docker, LAN, and remote deployments must configure the same\nrandom token in both processes:\n\n```bash\n# ComfyUI process\nCOMFYUI_MCP_BRIDGE_TOKEN=\"replace-with-a-long-random-value\" python main.py\n\n# MCP server process\nCOMFYUI_MCP_BRIDGE_TOKEN=\"replace-with-a-long-random-value\" uv run comfyui-mcp\n```\n\nCurrent bridge behavior:\n\n- `replace` clears the canvas before reconstructing the API graph.\n- `merge` adds the reconstructed graph to the existing canvas.\n- Nodes receive a deterministic layered layout because API-format workflows do not contain visual\n  positions.\n- Unknown custom nodes and unresolved links are reported as canvas warnings.\n- The event is broadcast to open ComfyUI browser sessions connected to that server.\n\nCanvas synchronization is a convenience and review surface, not the source of truth. The managed\nAPI workflow is what gets executed.\n\n## Configuration\n\n| Variable | Default | Purpose |\n| --- | --- | --- |\n| `COMFYUI_URL` | `http://127.0.0.1:8188` | ComfyUI base URL |\n| `COMFYUI_API_PREFIX` | empty | Prefix native routes; use `/api` for compatible cloud endpoints |\n| `COMFYUI_API_KEY` | empty | API key sent to ComfyUI |\n| `COMFYUI_API_KEY_HEADER` | `X-API-Key` | Header used for the API key |\n| `COMFYUI_ACCOUNT_API_KEY` | empty | Key placed in `extra_data` for paid Comfy API nodes |\n| `COMFYUI_MCP_BRIDGE_TOKEN` | empty | Shared token for the optional canvas bridge |\n| `COMFYUI_TIMEOUT_SECONDS` | `30` | HTTP request timeout |\n| `COMFYUI_VERIFY_SSL` | `true` | Verify the ComfyUI HTTPS certificate |\n| `COMFYUI_MCP_DATA_DIR` | OS user data dir | Workflow and output storage |\n| `COMFYUI_MCP_INPUT_ROOTS` | data dir | Allowed upload roots, separated by the OS path separator |\n| `COMFYUI_MCP_TRANSPORT` | `stdio` | `stdio`, `streamable-http`, or `sse` |\n| `COMFYUI_MCP_HOST` | `127.0.0.1` | HTTP bind host |\n| `COMFYUI_MCP_PORT` | `8000` | HTTP bind port |\n| `COMFYUI_MCP_ALLOW_REMOTE` | `false` | Permit non-loopback MCP HTTP binding |\n\nExample allowing two upload directories on Linux/macOS:\n\n```bash\nCOMFYUI_MCP_INPUT_ROOTS=\"/data/comfy-inputs:/home/me/reference-images\" uv run comfyui-mcp\n```\n\nUse `;` instead of `:` on Windows.\n\n## Local ComfyUI and Comfy Cloud\n\nThe implementation targets the stable local ComfyUI routes by default. A Comfy Cloud-compatible\ndeployment can use `COMFYUI_API_PREFIX=/api` and `COMFYUI_API_KEY`; cloud endpoint behavior and\navailable features may differ. The canvas bridge is intended for a ComfyUI instance where the\nbundled custom extension can be installed.\n\nDo not expose an unauthenticated local ComfyUI port directly to the internet. Put remote ComfyUI\nbehind an authenticated reverse proxy or a private network.\n\n## Development\n\n```bash\nuv sync --extra dev\nuv run pytest\nuv run ruff check .\nuv run ruff format --check .\n```\n\nRun the MCP Inspector against stdio:\n\n```bash\nuv run mcp dev src/comfyui_mcp/dev_server.py:mcp\n```\n\nOr start Streamable HTTP and connect the Inspector to `http://127.0.0.1:8000/mcp`:\n\n```bash\nuv run comfyui-mcp --transport streamable-http\nnpx -y @modelcontextprotocol/inspector\n```\n\n## Known limitations\n\n- Import currently accepts API-format workflows, not automatic conversion from arbitrary visual\n  workflow JSON.\n- The bridge reconstructs a practical graph layout; it cannot recover original groups, comments,\n  colors, or positions that are absent from API format.\n- Live progress is available from ComfyUI itself, while the current MCP API exposes pollable run\n  status rather than a long-running streaming tool call.\n- Some custom nodes rely on browser-only state and cannot run correctly in ComfyUI API mode.\n- Streamable HTTP authentication must currently be supplied by a trusted reverse proxy.\n\n## Roadmap\n\n- Bidirectional canvas editing and explicit visual-workflow import/export.\n- WebSocket-backed progress notifications and preview resources.\n- Workflow transactions for multi-edit atomic changes.\n- Safer policy profiles for paid nodes, model allowlists, and maximum image dimensions.\n- Packaging the canvas bridge for the ComfyUI Registry.\n- Compatibility fixtures for major MCP hosts and ComfyUI releases.\n\n## Contributing\n\nIssues and pull requests are welcome. Read [CONTRIBUTING.md](CONTRIBUTING.md) and\n[SECURITY.md](SECURITY.md) before publishing a change or vulnerability report.\n\n## License\n\nApache License 2.0. See [LICENSE](LICENSE).\n",
  "bytes": 14366,
  "sha": "28579b8d6429c4b90a02af1043e22d94b9dedcf848cd4f760e6dc7cbc34a8171",
  "repo_slug": "yutianxiao6/comfyui-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_yutianxiao6_comfyui_mcp_7f0353bd/readme"
}