comfyui-mcp
Build, inspect, validate, and run ComfyUI workflows through a local MCP server.
Open source Open in the app JSON README (API)
About
Build, inspect, validate, and run ComfyUI workflows through a local MCP server.
Details
- Kind
- Plugins
- Topic
- No topic detected
- Publisher
- yutianxiao6
- Origin
- gemini
- Category
- ferramentas
- Version
- 0.1.0
- Stars
- 2
- Last push
- 2026-08-05T04:31:34Z
- Repository state
- ativo
- Language
- Python
- License
- Apache-2.0
- Added
- 2026-09-01 22:01:09
- Updated
- 2026-09-01 22:01:09
- Origin id
yutianxiao6/comfyui-mcp
README
# ComfyUI MCP
[简体中文](README.zh-CN.md)
A universal [Model Context Protocol](https://modelcontextprotocol.io/) 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.
| Host | Included adapter | Local install or test |
| --- | --- | --- |
| Codex | `.codex-plugin/plugin.json` | `codex plugin marketplace add yutianxiao6/comfyui-mcp`, then `codex plugin add comfyui-mcp@comfyui-mcp` |
| Claude Code | `.claude-plugin/plugin.json` | `claude --plugin-dir /absolute/path/to/comfyui-mcp` |
| Gemini CLI | `gemini-extension.json` | `gemini extensions link /absolute/path/to/comfyui-mcp` |
| Cursor | `.cursor-plugin/plugin.json` | Link or copy into `~/.cursor/plugins/local/comfyui-mcp` |
| GitHub Copilot CLI | `.plugin/plugin.json` | `copilot plugins install /absolute/path/to/comfyui-mcp` |
| Other MCP clients | Generic example | Register `examples/mcp-client-config.example.json` |
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](docs/agent-integrations.md) for persistent install commands,
non-default ComfyUI URLs, explicit skill invocation, verification, and packaging details.
## 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
```text
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](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
```bash
git clone https://github.com/yutianxiao6/comfyui-mcp.git
cd comfyui-mcp
uv sync
uv run comfyui-mcp --version
```
With regular Python tooling:
```bash
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:
```bash
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:
```bash
COMFYUI_URL=http://127.0.0.1:8188 uv run comfyui-mcp
```
### Streamable HTTP
Use this when several clients need the same MCP endpoint:
```bash
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](SECURITY.md).
## Connect an MCP client
Most desktop and IDE clients accept the same `mcpServers` shape. Replace the repository path:
```json
{
"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](examples/mcp-client-config.example.json).
For an already running Streamable HTTP server, configure the client with:
```text
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:
```text
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
| Area | Tools |
| --- | --- |
| Connection | `comfyui_health` |
| Discovery | `comfyui_list_node_types`, `comfyui_get_node_type`, `comfyui_list_models`, `comfyui_list_templates` |
| Workflow store | `comfyui_list_workflows`, `comfyui_create_workflow`, `comfyui_import_workflow`, `comfyui_get_workflow` |
| Graph editing | `comfyui_add_node`, `comfyui_remove_node`, `comfyui_set_input`, `comfyui_connect_nodes`, `comfyui_disconnect_input` |
| Validation and canvas | `comfyui_validate_workflow`, `comfyui_sync_canvas` |
| Execution | `comfyui_run_workflow`, `comfyui_get_run`, `comfyui_get_queue`, `comfyui_interrupt`, `comfyui_clear_queue` |
| Files | `comfyui_upload_image`, `comfyui_download_output` |
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]`.
```json
{
"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:
```text
<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:
```bash
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:
```bash
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:
```bash
# 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
| Variable | Default | Purpose |
| --- | --- | --- |
| `COMFYUI_URL` | `http://127.0.0.1:8188` | ComfyUI base URL |
| `COMFYUI_API_PREFIX` | empty | Prefix native routes; use `/api` for compatible cloud endpoints |
| `COMFYUI_API_KEY` | empty | API key sent to ComfyUI |
| `COMFYUI_API_KEY_HEADER` | `X-API-Key` | Header used for the API key |
| `COMFYUI_ACCOUNT_API_KEY` | empty | Key placed in `extra_data` for paid Comfy API nodes |
| `COMFYUI_MCP_BRIDGE_TOKEN` | empty | Shared token for the optional canvas bridge |
| `COMFYUI_TIMEOUT_SECONDS` | `30` | HTTP request timeout |
| `COMFYUI_VERIFY_SSL` | `true` | Verify the ComfyUI HTTPS certificate |
| `COMFYUI_MCP_DATA_DIR` | OS user data dir | Workflow and output storage |
| `COMFYUI_MCP_INPUT_ROOTS` | data dir | Allowed upload roots, separated by the OS path separator |
| `COMFYUI_MCP_TRANSPORT` | `stdio` | `stdio`, `streamable-http`, or `sse` |
| `COMFYUI_MCP_HOST` | `127.0.0.1` | HTTP bind host |
| `COMFYUI_MCP_PORT` | `8000` | HTTP bind port |
| `COMFYUI_MCP_ALLOW_REMOTE` | `false` | Permit non-loopback MCP HTTP binding |
Example allowing two upload directories on Linux/macOS:
```bash
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
```bash
uv sync --extra dev
uv run pytest
uv run ruff check .
uv run ruff format --check .
```
Run the MCP Inspector against stdio:
```bash
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`:
```bash
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](CONTRIBUTING.md) and
[SECURITY.md](SECURITY.md) before publishing a change or vulnerability report.
## License
Apache License 2.0. See [LICENSE](LICENSE).