local-comfyui-mcp

# 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