comfyui-mcp: A Local-First Control Plane That Turns Any LLM Into a ComfyUI Operator

What comfyui-mcp actually does

Most ComfyUI MCP servers are thin connectors: they forward a prompt and return an image. comfyui-mcp is not that. The README calls it a full control plane. It reads what is installed locally, wires the graph, frees VRAM, and runs the render. The tool set includes authoring and editing the graph node by node, managing models and custom nodes, and executing workflows. It also ships AI skills: model-specific generation guides with curated download URLs, workflow recipes, troubleshooting, and custom-node authoring. The point is to give the LLM enough context to pick the right sampler, CFG, resolution, and model files without trial and error. The project targets engineers and artists who run ComfyUI themselves and want an agent that operates it, not just triggers it.

How the agent drives your live graph

The core mechanism is an MCP server that connects to a running ComfyUI instance. It auto-detects your install and port. The agent reads the current graph state, makes edits through MCP tools, and executes the workflow. The README highlights natural language editing of the live graph, including spatial layout and rewind/rollback. There is also a sidebar agent, the ComfyUI Agent Panel, available via ComfyUI-Manager. The panel runs on Claude, ChatGPT, Gemini, or any local or hosted LLM. It asks before spending paid API credits. The tools and the panel are the same on every tier, so switching models does not change the interface. The project includes an LLM Arena that scores each model on real ComfyUI tasks, so you can see what your model can actually do.

Getting it running: commands and config

The quick start is straightforward. Install ComfyUI first, then add the MCP server to your Claude Code config at ~/.claude/settings.json. The example config uses npx with the comfyui-mcp package and an optional CIVITAI_API_TOKEN environment variable. You do not clone the repo; npx downloads and runs it. With ComfyUI running, you can ask Claude to generate an image and it will find or download a checkpoint, build a workflow, execute it, and return the image. For remote access, the README shows a one-command tunnel: npx -y comfyui-mcp@latest --tunnel. This forces HTTP transport, generates an auth token, opens a cloudflared quick tunnel, and prints a URL and token for Claude Desktop connectors. Auth accepts either Authorization: Bearer or X-API-Key headers, matching Comfy Cloud's convention. Without a token or --tunnel, the default stdio behavior stays local and open.

Deployment modes and the local-first stance

The project is local-first, not local-only. The primary target is a self-hosted ComfyUI on macOS, Linux, or Windows. The same config can reach remote installs on LAN, VPS, RunPod, or reverse-proxied setups. There is also a community cloud mode using COMFYUI_API_KEY. The README is explicit that Comfy-Org ships its own agent tooling: Comfy Cloud MCP, an in-app agent, and a private Comfy Local MCP. If you do not have a GPU or want zero setup, the README says that is the better path. This project runs on your install and your choice of model, including a free local one via Ollama with no account and no network. That is a meaningful distinction: you keep your data and your model choices, but you take on the setup and maintenance burden.

Limitations and failure modes

The main limitation is that this is not a zero-setup solution. You need a working ComfyUI install, and the agent depends on the MCP server being able to reach it. The README warns that auth is opt-in; without a token, the server stays open and local, which is fine for local use but a risk if you expose it unintentionally. The --tunnel mode opens a public URL, which requires trusting cloudflared and the generated token. The README notes that OAuth is a planned follow-up, so browser sign-in is not available yet. Another limitation is that the AI skills are curated for specific models and architectures. If you use an obscure model or a custom node not covered by the skills, the agent may still struggle. The project's own comparison page acknowledges that Comfy Cloud's hosted agents are better for users who want zero setup. Also, the README lists 38 MCP tools and 42 AI skills, but those numbers change with each release, so you must check the current docs for the actual scope.

Alternatives and how they differ

The most direct alternative is Comfy-Org's own agent tooling, which the README describes in detail. Comfy Cloud MCP is a public beta hosted on Comfy Cloud GPUs. Comfy In-App Agent is a private alpha inside Comfy Cloud. Comfy Local MCP is a private test, not publicly available. The key difference is that Comfy's tools are hosted and maintained by the Comfy team, so you do not manage the server or the GPU. comfyui-mcp runs on your install and your model, including offline local models. If you want a minimal local relay, the README says a lightweight server is fine, but this project is not that. The choice comes down to whether you want to operate ComfyUI yourself or offload that to a hosted service. The README even tells you to go use Comfy's tools if you do not have a GPU or want zero setup.

Maintenance, license, and upgrade cost

The project is MIT-licensed, which means you can use, modify, and redistribute it freely, with attribution. The repository shows active development: multiple releases on the same day, with version numbers like v0.52.146, v0.52.145, and v0.52.144. That indicates a fast release cadence, which is good for features but means you should expect frequent updates. The README mentions that skills grow with every release, so upgrading may change the tool and skill counts. The maintenance cost is on you: you must keep the npx package updated and ensure compatibility with your ComfyUI version. The project auto-detects your install, but that does not guarantee compatibility with every custom node or model. The documentation is the primary source for upgrade notes, and the Discord is the support channel. There is no mention of a migration path or breaking changes in the supplied material, so verify the changelog before major upgrades.

Editorial conclusion

Adopt comfyui-mcp if you run ComfyUI locally and want an agent that can author and edit graphs node by node, manage models and custom nodes, and work with any LLM including free offline ones via Ollama. Skip it if you want a minimal relay or prefer Comfy's own hosted agent tooling, which the README itself recommends for zero-setup cloud use. Before committing, verify your ComfyUI version matches the plugin's expectations, test the --tunnel mode only if you need remote access, and check the docs for the current list of 38 MCP tools and 42 AI skills, as these numbers change with each release. The project is MIT-licensed and actively released, but its value depends on how well its curated skills match the models you actually use.

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes