> Looking for the cloud-hosted version? [Comfy Cloud MCP](#comfy-cloud-mcp) is set up below — install
> it instead of this server, or alongside it.
**What it does:**
- 🖼️ **Generate** — run a workflow JSON (API-format or UI export), or go text-prompt → image in one call.
- ⏱️ **Monitor jobs** — submit async, then wait / watch / cancel, read the failure verdict, and collect the output PNGs.
- 🔍 **Introspect your live install** — search the nodes, models, and templates your ComfyUI *actually* has (custom nodes included), not a static catalog.
- 🧩 **Build workflows** — validate a graph, edit a template's slots, and fan one workflow into variants.
- ♻️ **Manage ComfyUI** — launch / stop / restart the server, tail its logs, and stage input assets.
Each tool shells out to the `comfy` command with `--where local --json`, parses comfy-cli's
`envelope/1` output, and returns it — comfy-cli is the engine, and by default everything targets
the ComfyUI on **your** machine (`127.0.0.1:8188`).
**Scope — local-first, not local-only.** A few flows already reach beyond your machine:
[`partner_generate`](#spending-credits-on-partner-models) runs hosted partner models
(Flux / Ideogram / Kling / …) entirely on partner infrastructure — no local ComfyUI in the
execution path — and [partner-API nodes](#partner-api-nodes) let a locally-executed workflow call
those same hosted models, while [`COMFYUI_URL`](#driving-a-remote-comfyui) points the run/job tools
at a ComfyUI on another machine you control.
**This server vs. [Comfy Cloud MCP](#comfy-cloud-mcp).** Two different servers, and running both is
normal. This one is **stdio**: your client launches it as a subprocess on **your own machine**, and
it drives the ComfyUI installed there (or one on another machine you control). Comfy Cloud MCP is a
**remote HTTP** server at `https://cloud.comfy.org/mcp` that your client connects to over the
network, and it executes workflows on **Comfy Cloud GPUs** — no local GPU, no ComfyUI install. Both
authenticate: this one signs in to Comfy through comfy-cli ([`auth_login`](#partner-api-nodes) or
`COMFY_API_KEY`), the cloud one through OAuth in your browser or a Comfy Cloud API key. Both can
spend credits on **partner** models, so partner generation is not the dividing line — what this
server has no path to is Comfy Cloud itself: no cloud-hosted execution, no cloud queue, no
cross-session cloud batches. Every tool here shells out to `comfy --where local`. Pick by where you
want the work to run, or [install the cloud server too](#comfy-cloud-mcp).
> **Status:** beta. 40 tools; core loop validated end-to-end against a live local ComfyUI
> (`server_info → run_workflow → fetch_outputs` → PNG on disk). CI runs pytest + ruff on
> Python 3.10 and 3.14.
## Quickstart
Four steps take you from a fresh install to your first generated image.
1. **Install the pieces.**
```bash
pip install comfy-mcp "comfy-cli>=1.14.0" # this server + the engine it wraps
comfy install # create a ComfyUI workspace (skip if you have one)
```
**Both names, one command — on purpose.** Installing `comfy-mcp` does **not** install
comfy-cli: it is not a declared dependency of this package, because the server runs whichever
`comfy` binary your `PATH` (or [`COMFY_BIN`](#prerequisites)) resolves to, which is often not
the environment you installed the server into. Declaring it would put a second copy in this
venv that may not be the one your tools actually drive; the version that matters is checked at
**runtime** instead, against the binary really being called. Skip it and the server still
starts and completes the MCP handshake — every tool call then fails with "`comfy` not found on
PATH", which is a missing engine, not a broken install.
`pip install comfy-mcp` puts a `comfy-mcp` console script on your `PATH`; that command is what
you point your AI client at in step 3. (A dedicated venv is fine — MCP clients may not see that
venv's `PATH`, which is exactly what `COMFY_BIN` is for; see [Prerequisites](#prerequisites).)
`comfy-mcp --version` confirms it landed — but don't run `comfy-mcp` itself to test it: it
is a **stdio** server that talks MCP over stdin/stdout, so in a terminal it just waits and
exits without printing anything. `comfy-mcp --help` says the same thing in one screen.
To install from a checkout of this repo instead, run `pip install .` there (`pip install -e .`
for a working copy) — the comfy-cli half is the same either way.
> Installed this server back when it was called `comfy-local-mcp`? Do
> [Upgrading from `comfy-local-mcp`](#upgrading-from-comfy-local-mcp) first — installing
> `comfy-mcp` alone will **not** clean up after the old name.
2. **Launch ComfyUI** and leave it running:
```bash
comfy launch
```
3. **Add the server to your client** using the snippet for your client in
[Configure your AI client](#configure-your-ai-client) just below, then restart / reload it so
the tools appear.
4. **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 your workflow JSON (API-format or a UI export), and `fetch_outputs` to collect the
result. No hand-authored workflow? Ask it to start from a template instead — it can
`search_templates`, `fetch_template` to write a runnable JSON, and run that — and
`fetch_template` tells it up front if [your install can't run that
template](#templates-your-install-cant-run) yet.
**Where the images land.** ComfyUI writes generated files into your ComfyUI **workspace's
`output/` directory** (part of the workspace `comfy install` created). On top of that,
`fetch_outputs(prompt_id, out_dir)` **copies** a finished job's outputs into any directory you
name — so telling the agent "save them to `./outputs`" puts a copy right where you asked while
the originals stay in the ComfyUI workspace.
## Upgrading from `comfy-local-mcp`
This server used to be called **`comfy-local-mcp`**. It was never published to PyPI under that
name, so this only affects you if you installed it from a source checkout — but for those installs
the rename is **not** something `pip install .` finishes on its own, because `comfy-mcp` is a
*different distribution*, not a new version of the old one. Four things moved:
| Was | Is now |
| --- | --- |
| distribution / import package `comfy-local-mcp` / `comfy_local_mcp` | `comfy-mcp` / `comfy_mcp` |
| console script `comfy-local-mcp` (the `"command"` in your client config) | `comfy-mcp` |
| env var `COMFY_LOCAL_MCP_DEBUG_LOG` | `COMFY_MCP_DEBUG_LOG` |
| failure-log directory leaf `comfy-local-mcp/` | `comfy-mcp/` |
1. **Uninstall the old distribution first.** Installing the new one leaves the old one in place,
and its `comfy-local-mcp` script stays on your `PATH` pointing at a package that no longer
exists — so an "upgraded" environment either keeps running the old code or fails with
`ModuleNotFoundError`:
```bash
pip uninstall comfy-local-mcp # then: pip install comfy-mcp (or `pip install -e .`)
```
2. **Change `"command"` to `comfy-mcp`** in every MCP client config that starts this server
(`.mcp.json`, `claude_desktop_config.json`, `~/.cursor/mcp.json` — see
[Configure your AI client](#configure-your-ai-client)), then restart the client. The old
command name is gone; nothing aliases it.
3. **Rename the failure-log env var if you set it.** `COMFY_LOCAL_MCP_DEBUG_LOG` is no longer
read, and an env block that still sets it logs **nothing** — a disabled log and a stale
variable look identical from the outside. Use `COMFY_MCP_DEBUG_LOG`; see
[Failure log (opt-in)](#failure-log-opt-in).
4. **Move an existing failure log if you're mid-investigation.** The default path's directory leaf
changed with the package, so a fresh run starts an empty `failures.jsonl` rather than appending
to the trail you were collecting. Nothing reads the old directory any more — copy it across, or
delete it:
```bash
# macOS; ~/AppData/Local on Windows, ~/.config on Linux
cd ~/Library/Application\ Support
mkdir -p comfy-mcp
mv comfy-local-mcp/failures.jsonl* comfy-mcp/ && rmdir comfy-local-mcp
```
The glob carries the two rotations (`failures.jsonl.1`, `failures.jsonl.2`) along with the
live file, and `mkdir -p` first means this is also safe once the new directory exists.
## Configure your AI client
All three clients speak the same MCP stdio contract: run the `comfy-mcp` command as a
server. Pick your client.
> The **server key** (`comfy-mcp` in every snippet below) is just the label your client files
> these tools under — it is yours to choose, and the `"command"` (`comfy-mcp`) is the only part
> that has to match the installed console script. Earlier versions of this README used
> `comfy-local`, so **if your config already has a `comfy-local` entry, edit it rather than
> pasting a second one** — two keys pointing at the same command register the server twice and
> your client shows every tool twice. Keeping the old key is equally fine; nothing reads it.
> The `COMFY_BIN` env entry is shown in every example. Drop it if `comfy` is already on the
> environment your client launches the server with; keep it (pointing at the absolute path) if
> it isn't. `COMFY_API_KEY` is also shown, commented as optional — keep it only if you use
> [partner-API nodes](#partner-api-nodes) (Seedream / Veo / Kling / Gemini / …); drop it
> otherwise.
> **On macOS, keep ComfyUI out of `~/Documents`, `~/Desktop` and `~/Downloads`** — or grant your
> client Full Disk Access. macOS blocks apps (and everything they launch) from reading those
> folders, so an install there fails with `Operation not permitted` before anything runs. See
> [Troubleshooting](#troubleshooting).
### Claude Code
One command registers the server:
```bash
# COMFY_API_KEY is optional — add it only if you use partner-API nodes
# (see the Partner-API nodes section).
claude mcp add comfy-mcp \
-e COMFY_BIN=/path/to/venv/bin/comfy \
-e COMFY_API_KEY=
