# comfyui-mcp

**An MCP server that drives a local ComfyUI - including the workflow you have open in the browser.**

[English](README.md) | [Русский](README.ru.md) | [Changelog](CHANGELOG.md)

<p align="center">
  <a href="https://github.com/pytraveler/local-comfyui-mcp/releases/latest"><img alt="Latest release" src="https://img.shields.io/github/v/release/pytraveler/local-comfyui-mcp?display_name=tag"></a>
  <a href="LICENSE"><img alt="License" src="https://img.shields.io/github/license/pytraveler/local-comfyui-mcp"></a>
  <img alt="Python 3.11+" src="https://img.shields.io/badge/Python-3.11%2B-3776AB?logo=python&logoColor=white">
  <img alt="64 tools" src="https://img.shields.io/badge/tools-64-2ea44f">
  <a href="https://modelcontextprotocol.io"><img alt="MCP server" src="https://img.shields.io/badge/MCP-server-6E4AFF"></a>
  <a href="https://github.com/comfyanonymous/ComfyUI"><img alt="Drives a local ComfyUI" src="https://img.shields.io/badge/ComfyUI-local-1B98E0"></a>
</p>

---

Point your assistant at ComfyUI and it can list your workflows, work out what
parameters each one takes, run them, watch the progress, and show you the result.
With the optional bridge node installed it can also read and edit **the canvas on
screen**, unsaved changes and all.

```
you: run the ideogram workflow at 1.5 megapixels, portrait
     -> describe_workflow  finds `megapixels` and `aspect_ratio` and where they land
     -> run_workflow       submits, streams progress, returns the file
     -> show_image         you look at it
```

## Why the bridge is the interesting half

ComfyUI's HTTP API knows about files, models and the queue. It knows nothing
about the workflow being edited: that lives in litegraph, inside the page, and
the only copy of its unsaved state is in the tab's memory.

The bridge turns the WebSocket ComfyUI already holds open to every client into a
request/response channel, so an assistant can read the live graph, change widget
values, rewire links, tidy the layout, take a screenshot of the canvas, and queue
the workflow the same way the Queue button does.

It also goes the other way. A question can be put on the ComfyUI screen and
answered there - below the canvas rather than over it, so the graph stays visible
and usable while you decide. That is the whole point: the question worth asking
is "look at this and tell me", and a modal box covers the thing to look at.

Everything else works without it, and the tools say plainly which of the two
setup steps is missing rather than failing vaguely.

## Requirements

- **ComfyUI** - a portable build or any local install.
- **Nothing else.** The installer fetches [uv](https://github.com/astral-sh/uv),
  which then builds an isolated `.venv` with the right Python. No global Python,
  no system packages.
- An MCP client. Eleven are supported out of the box; see below.

## Install

**Windows**

```
install.bat
```

**Linux and macOS**

```
./install.sh
```

Five steps: fetch uv, build the `.venv`, seed `.env` from the template, check the
server imports, run the test suite. Safe to run again - each step checks whether
it is already done.

Prefer a menu to remembering names? `launcher.bat` / `./launcher.sh` opens one
window over every script in the folder, and installs first if there is no `.venv`
yet.

## Tell it where ComfyUI is

```
configure_comfy.bat        ./configure_comfy.sh
```

Root folder, port, launch script, the model and export directories, the download
token. The installer opens this window by itself if it cannot resolve
`COMFYUI_ROOT`. Everything it writes goes to `.env`; see `.env.example` for the
full list of settings.

## Connect your MCP client

```
configure_clients.bat      ./configure_clients.sh
```

Generates a ready config for **Claude Code, Cursor, Kilo Code, OpenCode, LM
Studio, Cherry Studio, MiMo Code, OpenClaw, Hermes, Codex and llama.cpp** - the
right shape, the right container key, the right file format, with the absolute
paths into this checkout already filled in. An existing config is merged rather
than replaced, and a file with comments in it is never rewritten.

## Install the bridge node

```
install_node.bat           ./install_node.sh
uninstall_node.bat         ./uninstall_node.sh
```

A directory junction (symlink on Unix) into `custom_nodes`, so there is no second
copy to drift. No administrator rights needed.

**Restart ComfyUI afterwards** - custom nodes are imported once at startup. After
that, opening a tab is all it takes; `workspace_status` says whether both halves
are in place.

## What the 64 tools cover

| Group | What it is for |
|---|---|
| **Status** | is ComfyUI up, what is the VRAM and the queue doing |
| **Workflows and reference** | list workflow files, work out their parameters, search the node catalogue, read a node's schema |
| **Logs** | ComfyUI's own console, and the browser console - where a failed extension is the only place it says anything |
| **Canvas: reading** | the live graph, a screenshot of it, which workflow tabs are open, a diagnosis of what is wrong with it |
| **Canvas: editing** | widget values, properties, on-screen labels, links, node modes, layout, groups, undo |
| **Asking the user** | put a question on the ComfyUI screen and wait for the person to answer |
| **Running** | run a file or the canvas, follow the progress, fetch the result, show an image |
| **Downloading models** | fetch a model to the directory ComfyUI actually reads, with progress |
| **Environment: reading** | what is installed in ComfyUI's Python and in custom_nodes, which packages have known vulnerabilities, and what an install would change before it changes it |
| **Environment: checkpoints** | record what is installed, and put a recorded state back |
| **Extensions: reading** | search the Comfy Registry, and report what one installed node pack is, where it came from and whether its nodes actually load |
| **Extensions: enabling and disabling** | turn an installed node pack off and on again, the way ComfyUI-Manager does |
| **Extensions: installing** | install a node pack from the Comfy Registry, move one to another released version, or install the requirements of one already on disk - each with the plan read and refused first, and a checkpoint written |
| **Process and tab** | start, stop or restart ComfyUI; reload the browser tab |

A ComfyUI **this server started** is stopped when the server exits, and stopping
it takes the whole tree rather than the launcher it runs behind. A ComfyUI **you
started yourself** is never touched by any of this. If the server is killed
outright its ComfyUI keeps running - the next server recognises it and can stop
it, but does not do so on its own, because a generation outlives an editor crash
and may still be running.

Not all of them have to be offered. `configure.bat` writes one line to `.env` that
narrows the set - a switched-off tool is not registered at all, so its schema
never reaches the model's context. What is off is reported by `comfy_status`, so
the assistant does not conclude the server cannot do it.

## Security

The server, ComfyUI and the browser tab all run on your own machine, under your
own account, over stdio. Nothing leaves it except the model downloads you ask
for. What follows is what that still leaves open, because "it runs locally" is
not the whole answer.

**The download is the sharp end.** A model URL routinely arrives from somebody
else's document - a "Model Links" note inside a shared workflow, or a loader's
`properties.models` - reaches the assistant as ordinary text, and the assistant
has a downloader. So `download_model` refuses three things before it opens a
socket, and refuses a `dry_run` the same way:

- **A host you did not allow.** `COMFYUI_DOWNLOAD_ALLOW_HOSTS` ships non-empty.
  An injected instruction can name any URL; it cannot name a host that is not on
  the list.
- **A format that executes as it loads.** `.ckpt .pt .pth .bin .pkl` are pickle;
  `.safetensors` and `.gguf` are data. Refused unless
  `COMFYUI_DOWNLOAD_ALLOW_PICKLE` says otherwise.
- **A file the volume cannot hold**, plus a ceiling of your own if you want one.

A download token, if you set one, reaches the origin host and no further: the
redirect chain is walked by hand so that a signed CDN link never sees it.

**There is no authentication by default, and ComfyUI has none either.** On
localhost that is the posture you already have. If ComfyUI listens wider than
that, set `COMFYUI_BRIDGE_TOKEN` here and `COMFYUI_MCP_BRIDGE_TOKEN` in
ComfyUI's own environment - the bridge adds routes to ComfyUI's server, and one
of them restarts the process.

**A ComfyUI behind a reverse proxy is the other half of that.** `COMFYUI_USER`
and `COMFYUI_PASSWORD` send Basic Auth on both the HTTP calls and the WebSocket,
which is what a proxy asking for credentials in front of the whole API needs -
where the bridge token guards only the bridge's own routes. Set both or neither:
one alone authenticates with nothing, and `comfy_status` says so rather than
leaving you with a bare 401. The password goes in `.env`, not into the URL, where
it would show up in process lists, logs and error text.

**After editing `.env`, restart the server process.** Reconnecting from the MCP
client makes a new session against the same process, and the configuration was
read once when that process started - so a reconnect leaves the old values in
place with nothing saying so.

**The tool switch is not a security boundary**, and the tool descriptions say so.
`configure.bat` decides what is offered, which is a coarse grid: the question
about `download_model` is not whether it exists but where it may point, and that
is what the settings above are for. Your MCP client's own permission prompts are
the other half.


## Workflows

Workflow files live in `workflows/` and must be **API format** -
`Workflow -> Export (API)` in ComfyUI. A UI-format export is refused with an
explanation rather than half-read.

A workflow may ship a same-named `.md` beside it: an instruction file for whoever
fills the parameters in, served verbatim by `get_workflow_guide`. Some graphs
need input in a shape the node list cannot express, and prose gets you nowhere.

## Two languages

Every window, the installer and `.env.example` speak English or Russian.
`COMFYUI_LANG` decides; left empty it asks the machine. `--lang=en` opens any
window in the other language for one run.

The tool descriptions the model reads stay English throughout, deliberately: they
describe an interface to a program.

## When something is wrong

- A node type cannot be found, or a pack behaves as though half of it is missing:
  read `get_comfy_log`. A custom node whose import failed is simply absent from
  `/object_info`, and absent looks exactly like never installed.
- A node is on the canvas but behaves wrongly: read `get_console_log`. The
  frontend catches an extension's import error and only logs it to the browser
  console, so that is the only place it exists.
- A workspace tool fails: `workspace_status` names which of the two things is
  missing - the node, or an open tab. Neither is worth retrying.

## Licence

[GPL-3.0](LICENSE). ComfyUI itself is GPL-3.0, and the bridge half of this
project is a custom node that runs inside it, so the same terms are the honest
fit: use it, change it, distribute it - and pass the source and the credit along
with it.

Copyright (C) 2026 pytraveler