docs(agent-tools): add Comfy Local MCP as the first-party local option #1236
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,156 @@ | ||
| --- | ||
| title: "Comfy Local MCP" | ||
| sidebarTitle: "Local MCP" | ||
| description: "Drive your own local ComfyUI from AI agents (Claude Code, Claude Desktop, Cursor) with the first-party comfy-local-mcp server — run workflows, collect outputs, and inspect the nodes and models your install actually has." | ||
| icon: "server" | ||
| --- | ||
|
|
||
| <Warning> | ||
| **Early preview.** `comfy-local-mcp` is an early proof-of-concept. The core loop (`server_info → run_workflow → fetch_outputs`) is validated end-to-end against a live local ComfyUI, but tools and behavior may still change. | ||
| </Warning> | ||
|
|
||
| [**comfy-local-mcp**](https://github.com/Comfy-Org/comfy-local-mcp) is Comfy's **first-party local MCP server** — the official way to drive a **local** ComfyUI install from AI agents (Claude Code, Claude Desktop, Cursor, and other MCP clients). It is a thin wrapper over [comfy-cli](https://github.com/Comfy-Org/comfy-cli): each tool shells out to the `comfy` command, so `comfy-cli` is the engine and there is no code shared with the [Comfy Cloud MCP](/agent-tools/cloud). | ||
|
|
||
| Unlike the cloud and partner servers, it talks to the ComfyUI running on **your own machine** — so it can run your workflows and inspect the nodes, custom nodes, and models your install actually has. | ||
|
|
||
| --- | ||
|
|
||
| ## Requirements | ||
|
|
||
| - **Python 3.10+** | ||
| - **[comfy-cli](https://github.com/Comfy-Org/comfy-cli)** on your `PATH` (`pip install comfy-cli`) — the engine every tool wraps | ||
| - **A ComfyUI workspace** — create one with `comfy install` if you don't have one (an existing checkout works via `comfy set-default <path>`) | ||
| - **A running ComfyUI** — start it with `comfy launch` before using the tools; nothing here launches ComfyUI implicitly | ||
|
|
||
| --- | ||
|
|
||
| ## Installation | ||
|
|
||
| From a checkout of the [repository](https://github.com/Comfy-Org/comfy-local-mcp): | ||
|
|
||
| ```bash | ||
| pip install . # or `pip install -e .` for a working copy | ||
| ``` | ||
|
|
||
| This puts a `comfy-local-mcp` console script on your `PATH` — that command is the MCP server (it speaks MCP over stdio). Point your AI client at it below. | ||
|
|
||
| <Note> | ||
| **`COMFY_BIN` (optional).** MCP clients launch the server with their own environment, which often does **not** include your shell's `PATH`. If `comfy` lives in a virtualenv or a non-standard location, set `COMFY_BIN` to its absolute path (for example `/path/to/venv/bin/comfy`). Every client example below shows where it goes; drop it if `comfy` is already on the environment your client launches the server with. | ||
| </Note> | ||
|
|
||
| --- | ||
|
|
||
| ## Configure your AI client | ||
|
|
||
| All clients speak the same MCP stdio contract: run the `comfy-local-mcp` command as a server. Pick your client. | ||
|
|
||
| ### Claude Code | ||
|
|
||
| One command registers the server: | ||
|
|
||
| ```bash | ||
| claude mcp add comfy-local -e COMFY_BIN=/path/to/venv/bin/comfy -- comfy-local-mcp | ||
| ``` | ||
|
|
||
| Or check it into a project with a `.mcp.json` at the repo root: | ||
|
|
||
| ```json | ||
| { | ||
| "mcpServers": { | ||
| "comfy-local": { | ||
| "command": "comfy-local-mcp", | ||
| "env": { "COMFY_BIN": "/path/to/venv/bin/comfy" } | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ### Claude Desktop | ||
|
|
||
| Edit `claude_desktop_config.json` (Settings → Developer → Edit Config; on macOS it lives at `~/Library/Application Support/Claude/claude_desktop_config.json`), add the server, then restart Claude Desktop: | ||
|
|
||
| ```json | ||
| { | ||
| "mcpServers": { | ||
| "comfy-local": { | ||
| "command": "comfy-local-mcp", | ||
| "env": { "COMFY_BIN": "/path/to/venv/bin/comfy" } | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ### Cursor | ||
|
|
||
| Add the server to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (per project): | ||
|
|
||
| ```json | ||
| { | ||
| "mcpServers": { | ||
| "comfy-local": { | ||
| "command": "comfy-local-mcp", | ||
| "env": { "COMFY_BIN": "/path/to/venv/bin/comfy" } | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| --- | ||
|
|
||
| ## Quickstart | ||
|
|
||
| Zero to a generated image: | ||
|
|
||
| <Steps> | ||
| <Step title="Install the pieces"> | ||
| ```bash | ||
| pip install comfy-cli # the engine | ||
| comfy install # create a ComfyUI workspace (skip if you have one) | ||
| pip install . # this MCP server → the `comfy-local-mcp` command | ||
| ``` | ||
| </Step> | ||
| <Step title="Launch ComfyUI and leave it running"> | ||
| ```bash | ||
| comfy launch | ||
| ``` | ||
| </Step> | ||
| <Step title="Add the server to your client"> | ||
| Use the snippet for your client above, then restart / reload it so the tools appear. | ||
| </Step> | ||
| <Step title="Ask your agent to run a workflow"> | ||
| For example: | ||
|
|
||
| > "Confirm my local ComfyUI is running, then run the workflow at `~/workflows/txt2img.json` and show me the image." | ||
|
|
||
| Under the hood the agent calls `server_info` to confirm ComfyUI is up, `run_workflow` to execute the workflow JSON, and `fetch_outputs` to collect the result. | ||
| </Step> | ||
| </Steps> | ||
|
|
||
| --- | ||
|
|
||
| ## Tools | ||
|
|
||
| Each tool maps onto a `comfy-cli` command, run with `--where local`. Highlights: | ||
|
|
||
| | Tool | Purpose | | ||
| |---|---| | ||
| | `server_info()` | Is a local ComfyUI running, where, and which workspace. **Call first.** | | ||
| | `run_workflow(workflow_path, wait=True)` | Run a workflow JSON; `wait=False` submits async and returns a `prompt_id`. | | ||
| | `job_status` / `wait_for_job` / `watch_job` | Poll, wait on, or stream a submitted job. | | ||
| | `fetch_outputs(prompt_id, out_dir)` | Copy a finished job's outputs into `out_dir`. | | ||
| | `launch_comfyui` / `stop_comfyui` | Start or stop the local ComfyUI. | | ||
| | `search_templates` / `fetch_template` | Find a built-in template and write its runnable workflow JSON. | | ||
| | `search_nodes` / `get_node` / `list_nodes` | Inspect the node classes in your **live local** install (custom nodes included). | | ||
| | `search_models` | List the model files on disk. | | ||
| | `validate_workflow` | Pre-flight a workflow against the live `object_info` before a slow run. | | ||
|
|
||
| Node introspection and model search read your **live install** — custom nodes included — which is the local differentiator from the cloud MCP. See the [repository](https://github.com/Comfy-Org/comfy-local-mcp) for the full tool list and reference. | ||
|
|
||
| --- | ||
|
|
||
| ## Related | ||
|
|
||
| - [Comfy Cloud MCP](/agent-tools/cloud) — hosted MCP server, no local install or GPU needed | ||
| - [Comfy Partner MCP](/agent-tools/partner-mcp) — local server for 30+ partner providers via the Comfy API | ||
| - [Comfy CLI](/agent-tools/comfy-cli) — drive local ComfyUI and partner generation from the terminal | ||
| - [comfy-local-mcp on GitHub](https://github.com/Comfy-Org/comfy-local-mcp) — source, install, and tool reference | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🌐 Web query:
Doesclaude mcp add -e KEY=VALUE --(env flag after the server name) work correctly in the current Claude Code CLI, or is env flag placement before the name required?💡 Result:
In the current Claude Code CLI, the environment variable flag must be placed before the server name. Placing the env flag after the server name is not supported and will cause the command to fail or be parsed incorrectly [1][2][3]. According to official documentation and technical discussions, all configuration options—including
--env(or-e),--transport, and--scope—must precede the server name [1][2][3]. The--separator is then used to delineate the end of these configuration flags and the start of the command that launches the server [4][5]. A known issue in the CLI exists where the parser may greedily consume the server name as part of the env-var value if the syntax is not strictly followed [6]. To ensure the command is parsed as intended, you should use the following order: claude mcp add [OPTIONS] -- [args...] For example: claude mcp add --env KEY=VALUE --transport stdio -- Documentation explicitly advises placing at least one other option (such as --transport) between the --env flag and the server name if you encounter parsing difficulties, as this helps prevent the CLI from incorrectly treating the server name as an additional environment variable pair [4][5].Citations:
claude mcp addbetween Documentation Text and Interactive Code Generator anthropics/claude-code#19120--separator forclaude mcp addanthropics/claude-code#18722Move
-ebefore the server nameclaude mcp add comfy-local -e COMFY_BIN=/path/to/venv/bin/comfy -- comfy-local-mcpis parsed incorrectly on supported Claude Code versions. Useclaude mcp add -e COMFY_BIN=/path/to/venv/bin/comfy comfy-local -- comfy-local-mcpinstead. Tiny typo, big nope.🤖 Prompt for AI Agents