comfyui-mcp: an agent control plane for your own ComfyUI install

What comfyui-mcp is for, and who it is not for

ComfyUI is a node graph. Driving it from a chat window means an agent has to do more than forward a prompt: it has to know which checkpoint exists on disk, which sampler and CFG suit that architecture, how to wire the nodes, and how to free VRAM before the next run. The README draws this line explicitly, calling most ComfyUI MCP servers thin connectors that forward a prompt and hand back an image, and positioning this project as a control plane instead.

The intended user runs ComfyUI on their own machine, LAN box, VPS or a rented GPU pod, and wants an assistant to operate it. The README states that the project is local-first, not local-only, and that a self-hosted install on Mac, Linux or Windows is the primary target. Model choice is deliberately open: Claude or ChatGPT on a subscription, Gemini through a Google login, a local model through Ollama with no account and no network, or any hosted model over one API key.

The user it is not for is stated just as plainly. For people without a GPU, or who want zero setup, the README says Comfy Cloud's own agent tooling is the better path and tells them to go use it. That is an unusual thing for a project README to say about a competitor, and it is worth taking at face value.

How the server reaches your ComfyUI instance

The mechanism is the Model Context Protocol. The package registers as an MCP server, and the client calls tools on it. The README's headline numbers describe a large surface: 38 MCP tools, 42 AI skills, 56 installer packs, 11 slash commands, 4 autonomous agents and 3 hooks in the plugin build. The package description in package.json gives a different count, 108 tools and 29 skills, which suggests the README's figures lag the code. Either way the surface is wide, and the project acknowledges the cost of that width.

That cost is the compact tool mode. The .env.example file explains that compact mode registers only list_tools, describe_tool and call_tool meta-tools instead of the full schema surface, and that this exists for small or local LLMs such as Hermes Agent and Ollama. The key is COMFYUI_MCP_TOOL_MODE, with values compact (the documented default) and full, and it maps to a --compact flag. A 4B local model cannot juggle a couple hundred tool schemas, so the router collapses them behind three meta-tools.

Connection details live in environment variables. COMFYUI_HOST defaults to 127.0.0.1 and COMFYUI_PORT to 8188. For a remote self-hosted instance behind a reverse proxy, COMFYUI_URL preserves a path prefix such as /comfyapi, and COMFYUI_AUTH_HEADER, COMFYUI_AUTH_SCHEME and COMFYUI_AUTH_TOKEN attach a generic auth header to every ComfyUI request. The .env.example is careful to note this is not Comfy Cloud, which is a separate mode keyed by COMFYUI_API_KEY.

There is also a split-install case worth knowing about. If your ComfyUI code checkout and your data root are in different places, COMFYUI_PATH stays the data root while COMFYUI_CODE_PATH points at the checkout containing main.py and .venv. That detail only matters on runtimes started with --base-directory, but when it applies, getting it wrong means the server looks in the wrong place for models.

Installing comfyui-mcp and asking for a first image

The README is explicit that you do not clone the repository. The server is published to npm and runs through npx, so the install step is a config edit. Add an entry to your Claude Code settings file at ~/.claude/settings.json:

{
  "mcpServers": {
    "comfyui": {
      "command": "npx",
      "args": ["-y", "comfyui-mcp"],
      "env": {
        "CIVITAI_API_TOKEN": ""
      }
    }
  }
}

The CIVITAI_API_TOKEN key is present but empty in the README's example. It is optional and only needed if you want the agent to pull models from Civitai.

Start ComfyUI, then ask the client for an image in plain language. The README's example prompt is a sunset over mountains. According to the README, the agent will find or download a checkpoint, build a workflow, execute it and return the image. That sequence is the whole pitch in one interaction: the agent is choosing a model file and wiring nodes, not just posting to an endpoint.

If you want the server reachable from Claude Desktop's Custom Connectors or another remote client, the README gives a single-flag path:

npx -y comfyui-mcp@latest --tunnel

That forces the HTTP transport, generates an auth token, opens a cloudflared quick tunnel and prints a paste-ready https URL, the token, and a Claude Desktop connector snippet. Auth accepts either Authorization: Bearer <token> or X-API-Key: <token>. The README notes auth is opt-in: with no COMFYUI_MCP_HTTP_TOKEN set and no --tunnel flag, the default stdio behaviour is unchanged and stays local. OAuth is described as a planned follow-up, not a shipped feature.

For panel users, the .env.example says keys are managed through an API Keys card in the interface, and that real environment variables always win over values in the file. The only .env location read is ~/.comfyui-mcp/.env; a legacy package-root .env is migrated there once and then ignored.

The agent panel and the Claude Code plugin are separate installs

Two distribution channels sit alongside the npm package, and confusing them is easy. The first is the ComfyUI Agent Panel, published on the Comfy Registry and installable by searching comfyui-agent-panel in ComfyUI-Manager. It puts an agent in the ComfyUI sidebar and runs on Claude, ChatGPT, Gemini or any local or hosted LLM. The README says it asks before spending paid API credits, supports rewind and rollback, and handles multi-tab and pending-message trays.

The second is the Claude Code plugin, which the repository ships as a .claude-plugin directory plus a plugin directory and a packs directory. The plugin is where the skills, slash commands and installer packs live. The README frames the skills as the differentiator: model-specific generation guides with curated download URLs, workflow recipes, troubleshooting and custom-node authoring, so the model knows the right sampler, CFG and resolution for each architecture.

Both channels depend on the same underlying server, which is why the README says the tools and the panel are the same on every tier. If you install only the npm package you get the tools without the sidebar; if you install only the panel you get the sidebar without your editor's MCP integration.

Where comfyui-mcp gets in the way

The tool surface is the main risk. A project that ships 38 tools in one count and 108 in another, with a router mode to hide them from small models, is telling you that the interface is large enough to be a problem. Compact mode is the documented answer, but it is a trade-off rather than a fix: routing every call through list_tools, describe_tool and call_tool adds a round trip and puts the model's understanding of the available operations one layer further from the actual schema.

The release cadence is a second consideration. The version in package.json is 0.52.203, and the recent releases listed are 0.52.146, 0.52.145 and 0.52.144, all dated 2026-08-28. That is a pre-1.0 project publishing multiple patch releases in a day. Nothing in the README promises interface stability, and a client config that pins nothing will pick up whatever npx resolves.

The remote path deserves care too. The --tunnel flag opens a cloudflared quick tunnel and prints a URL. Auth is opt-in, and the README states that without COMFYUI_MCP_HTTP_TOKEN and without --tunnel, the default is open and local. If you expose the server, the token is what stands between the internet and your GPU and your model files. The README does not document rollback for a compromised tunnel URL, so treat the printed URL as a secret.

Finally, the README does not document what happens when ComfyUI is unreachable, when a custom node is missing, or when a workflow references a checkpoint that is not on disk. Those failure paths are not described, and an agent that is confidently wiring a graph against a missing model is a worse experience than an error message.

How it differs from a minimal ComfyUI MCP relay

The honest alternative is a thin ComfyUI MCP server that exposes a prompt-and-return-image call. The README describes that category directly and says a lightweight server is fine if that is what you want. The difference is where the intelligence sits. A relay assumes you already know the checkpoint, sampler, CFG and resolution, and it moves bytes. comfyui-mcp moves the model-selection and graph-construction decisions into the agent, backed by the skill files in the plugin.

That is a real architectural difference, not a marketing one. A relay has a small tool surface, so it works with small models and rarely breaks on a client update. This project has the opposite profile: more capability, more surface, more to keep in sync. If your workflow is one fixed graph you run repeatedly with different prompts, the relay is the lower-maintenance choice and the extra skills buy you nothing.

Comfy-Org's own tooling is the other comparison the README raises. It lists Comfy Cloud MCP as a public beta hosted on Comfy Cloud GPUs, the Comfy In-App Agent as a private alpha inside Comfy Cloud, and a first-party Comfy Local MCP as a private test that is not publicly available. The README marks those statuses as of July 2026 and tells readers to check Comfy's docs for the current state. The practical split is ownership: Comfy's tools run on Comfy's infrastructure, while comfyui-mcp runs on your install with your choice of model, including a fully offline local one.

Licence, maintenance and what upgrading costs you

The licence is MIT, per the repository metadata. That permits commercial use, modification and redistribution provided the copyright notice and permission notice are included. It is a permissive licence with no copyleft obligation and no source-disclosure requirement for your own code. This is a description of the licence text, not legal advice; if you are embedding the project in a product, read the LICENSE file in the repository root yourself.

The maintenance signal is mixed in a specific way. The repository is not archived, and the last push was on 2026-08-28. The release history shows three versions published within roughly four hours on that date, which indicates active work rather than a dormant project. It also means the project is still pre-1.0 and shipping fast.

Upgrade cost is therefore real. The package is installed through npx without a pinned version in the README's example, so a client restart can pull a newer build than the one you validated. The tool surface has already shifted between the README's counts and package.json's counts, and the compact mode default lives in an environment variable you can set. If you need reproducibility, pin the version in your MCP config's args rather than accepting whatever npx resolves, and check CHANGELOG.md before moving the pin.

Editorial conclusion

Adopt comfyui-mcp if you already run ComfyUI yourself, want the agent to operate the graph rather than just submit a prompt, and are willing to keep a fast-moving plugin in sync with your client. Do not adopt it if you have no local GPU and want zero setup, since the README points those users at Comfy Cloud's own agent tooling instead. Before committing, verify three things: that your ComfyUI host and port are reachable from the machine running the MCP server, that your chosen model can handle the tool surface you expose (the compact mode exists precisely because small models struggle with the full one), and that your client's config file is one you are willing to edit, since that is where the server entry lives.

Frequently asked questions

Official sources

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