Comfy MCP is Comfy’s official Model Context Protocol server for local ComfyUI. Install comfy-cli and comfy-mcp, point your MCP client at the two executables, launch ComfyUI, and the agent can inspect the setup, validate an API-format or exported UI workflow, run it and retrieve the output.
That is the short version. The detail that saves the most frustration is that two different processes are involved: comfy launch runs ComfyUI, while your AI client starts comfy-mcp as a local stdio server. Running comfy-mcp by itself can therefore look as if it has frozen. It has not; it is quietly waiting for an MCP client.
Verified scope: I checked this guide against Comfy’s official documentation, repository and PyPI pages on 13 August 2026. I have not run a generation on my own hardware for this article, so I will not dress documentation review up as a hands-on benchmark. Comfy MCP is also a public beta: commands, tools and behaviour can change.
What Comfy MCP actually does
Comfy MCP gives an MCP-capable agent a control layer for ComfyUI. The official server exposes 39 tools covering tasks such as discovering models, nodes and templates; checking server information; validating workflows; starting a run; monitoring it; and fetching generated outputs.
My take is that this is more useful than another chat wrapper. A coding agent can reason about a workflow and then hand the actual image job to the ComfyUI instance already on your machine. You keep the flexibility of ComfyUI’s node graph while avoiding a fair amount of manual hopping between windows.
| Part | What it does | Where it runs |
|---|---|---|
| Your MCP client | Plans the task and calls the available tools | Claude Code, Cursor, Claude Desktop or another compatible client |
comfy-mcp | Translates those tool calls into ComfyUI actions | Locally over stdio |
| ComfyUI | Loads the workflow and performs the generation | Normally at 127.0.0.1:8188 |
| Partner API nodes | Call optional hosted models or services | Remote; these may consume credits |
Local does not automatically mean offline. A normal local workflow can keep its processing on your machine, but partner API nodes, third-party custom nodes or other networked components may still contact external services. Check the workflow before running it.
What you need before installing
- Python 3.10 or newer. I use Python 3.11 in the examples because it is a conservative choice for a fresh virtual environment.
comfy-cliversion 1.14.0 or newer, available on the path used by the MCP server.- A ComfyUI workspace, either created with
comfy installor selected withcomfy set-default. - An MCP client that can start a local stdio server.
- The models and custom nodes required by the workflow you intend to run.
A realistic hardware check
The MCP bridge itself is not the demanding part; the selected ComfyUI workflow is. The project gives the following routing guidance, which should not be mistaken for a performance guarantee:
- A discrete GPU with at least 24GB of VRAM is a strong default for local generation.
- With 8GB to under 24GB of VRAM, local image workflows may be practical, while video can be slow or infeasible.
- With less than 8GB of VRAM or no GPU, a hosted or partner route is generally more practical.
- On Apple Silicon, the project’s guidance treats 32GB or more of unified memory as suitable for local images, but does not recommend local video; below 32GB, it favours hosted options.
The exact result still depends on the model, resolution, quantisation, custom nodes and available memory. Do not buy hardware based on those broad bands alone.
Step 1: Install Comfy MCP on Windows
Use a dedicated virtual environment. It keeps this setup away from unrelated Python packages and gives you stable executable paths for the MCP configuration.
mkdir comfy-mcp-guide
cd comfy-mcp-guide
py -3.11 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install "comfy-cli>=1.14.0" comfy-mcp
where.exe comfy
where.exe comfy-mcp
comfy-mcp --versionKeep the two paths printed by where.exe. You will use them in the client configuration. If PowerShell blocks the activation script, you can install without activation:
.\.venv\Scripts\python.exe -m pip install --upgrade pip
.\.venv\Scripts\python.exe -m pip install "comfy-cli>=1.14.0" comfy-mcp
.\.venv\Scripts\comfy-mcp.exe --versionStep 2: Install Comfy MCP on macOS or Linux
mkdir -p ~/tools/comfy-mcp
cd ~/tools/comfy-mcp
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install "comfy-cli>=1.14.0" comfy-mcp
command -v comfy
command -v comfy-mcp
comfy-mcp --versionIf python3 -m venv is unavailable on your Linux distribution, install its Python venv package through the distribution’s normal package manager, then repeat the command. Keep the absolute paths returned by command -v.
Step 3: Create or select the ComfyUI workspace
For a new managed ComfyUI installation, run:
comfy installIf ComfyUI is already installed, tell comfy-cli which workspace to use:
# Windows example
comfy set-default "D:\AI\ComfyUI"
# macOS or Linux example
comfy set-default "/home/your-name/ComfyUI"Replace the example with the real ComfyUI directory. On macOS, the project recommends keeping ComfyUI outside Documents, Desktop and Downloads unless your MCP client has Full Disk Access. A folder such as ~/ComfyUI avoids an unnecessary permissions fight.
Step 4: Launch ComfyUI
comfy launchLeave that process running. The normal local address is 127.0.0.1:8188. Comfy MCP does not silently launch ComfyUI during startup; it only does so if an agent explicitly invokes the available launch_comfyui tool.
Step 5: Connect Claude Code
The official quick-start registers a server named comfy-mcp and supplies COMFY_BIN. An absolute executable path is less fragile than relying on an activated terminal.
Windows PowerShell
claude mcp add comfy-mcp -e COMFY_BIN=C:/Users/you/tools/comfy-mcp-guide/.venv/Scripts/comfy.exe -- C:/Users/you/tools/comfy-mcp-guide/.venv/Scripts/comfy-mcp.exemacOS or Linux
claude mcp add comfy-mcp \
-e COMFY_BIN=/home/you/tools/comfy-mcp/.venv/bin/comfy \
-- /home/you/tools/comfy-mcp/.venv/bin/comfy-mcpReplace every path with the one printed on your machine. Forward slashes are convenient in the Windows example because they also avoid JSON escaping problems later.
Step 6: Connect Cursor or Claude Desktop
Both clients use an mcpServers object. Add the following shape to the appropriate MCP settings file for your client.
Windows JSON
{
"mcpServers": {
"comfy-mcp": {
"command": "C:/Users/you/tools/comfy-mcp-guide/.venv/Scripts/comfy-mcp.exe",
"env": {
"COMFY_BIN": "C:/Users/you/tools/comfy-mcp-guide/.venv/Scripts/comfy.exe"
}
}
}
}macOS or Linux JSON
{
"mcpServers": {
"comfy-mcp": {
"command": "/home/you/tools/comfy-mcp/.venv/bin/comfy-mcp",
"env": {
"COMFY_BIN": "/home/you/tools/comfy-mcp/.venv/bin/comfy"
}
}
}
}Save the file, fully restart the client, and check its MCP or tools panel for comfy-mcp. The COMFY_BIN variable is optional when the client’s environment can already find comfy, but setting the absolute path removes guesswork.
Step 7: Run a first workflow
Start with a small workflow you already understand, saved as ComfyUI API JSON or a UI-exported workflow. Do not make the first test a giant graph downloaded from a stranger. A known workflow makes missing models, missing custom nodes and MCP problems much easier to separate.
With ComfyUI running, give the MCP client the official quick-test style of instruction:
Confirm my local ComfyUI is running, then run the workflow at
~/workflows/txt2img.jsonand show me the image.
Replace the file path with your own. Under the hood, the core loop is straightforward: server_info checks the instance, run_workflow submits the graph, and fetch_outputs retrieves the result. For an unfamiliar graph, ask the agent to validate it before running it.
A safer first prompt is:
Check my local ComfyUI server, validate the API workflow at
C:/AI/workflows/txt2img.json, and tell me about any missing nodes or models.
Do not run it until I approve the validated workflow.That approval boundary is my recommended addition to the official quick start. MCP makes the workflow convenient, but it also makes a powerful local application available to the agent. Convenience should not erase review.
Privacy and spend safeguards worth setting now
- Use an isolated ComfyUI workspace. Keep private files and unrelated projects outside the folders the agent needs.
- Keep ComfyUI bound to localhost. Do not expose port 8188 to the public internet simply to make this setup work.
- Review third-party workflows and custom nodes. They are code and configuration from outside the core project, not harmless pictures.
- Keep client approval prompts enabled. Ask the agent to validate before it runs or downloads anything.
- Do not put secrets in launch arguments or paths. The
system_statstool can expose the full launch command line to the model context. - Only set
COMFY_API_KEYwhen you need partner API nodes. Those nodes can use hosted services and consume credits. Incomfy-cli1.14 and newer, recognised partner-node spending is designed to fail closed without confirmation, but that does not guarantee protection from every paid third-party custom node. Read each confirmation and review unfamiliar nodes.
The repository says the custom Comfy user-agent does not include prompts, workflows or outputs. The wider comfy-cli telemetry setting still applies. If you prefer to opt out, the documented command is:
comfy tracking disableThe project also recognises the DO_NOT_TRACK and COMFY_NO_TELEMETRY environment variables. Remember that telemetry preferences do not stop a workflow’s partner nodes or custom nodes from making their own network calls.
Troubleshooting Comfy MCP
comfy-mcp opens but prints nothing
That is normal when you run a stdio MCP server directly. Press Ctrl+C, confirm the package with comfy-mcp --version, and let Claude Code, Cursor or the other MCP client start it.
The client says comfy or comfy-mcp was not found
The client does not inherit the virtual environment you activated in another terminal. Put the full comfy-mcp executable path in command and the full comfy path in COMFY_BIN. Restart the client after editing its configuration.
The tools appear, but the server cannot reach ComfyUI
Run comfy launch and confirm the local ComfyUI instance is available at its expected address, normally 127.0.0.1:8188. Also confirm that comfy-cli is pointing at the intended default workspace.
The workflow fails validation
Check that the file is a valid ComfyUI API-format workflow or UI export, and that every referenced model and custom node is installed in the selected workspace. Ask the agent to report the missing item rather than repeatedly submitting the same graph.
Windows reports invalid JSON
Backslashes in JSON must be escaped. The easiest fix is to use forward slashes in the Windows executable paths, as the configuration example above does.
Every Comfy tool appears twice
Look for duplicate MCP entries. In particular, do not register both the old comfy-local-mcp command and the current comfy-mcp command.
You previously installed comfy-local-mcp from source
python -m pip uninstall comfy-local-mcp
python -m pip install comfy-mcpThen change the MCP command from comfy-local-mcp to comfy-mcp. The debug environment variable also changed to COMFY_MCP_DEBUG_LOG. Remove the old registration rather than leaving both active.
Where this fits in a local AI setup
Comfy MCP is the image-workflow equivalent of giving an agent a carefully scoped local tool. If you are building a broader MCP setup, my llama.cpp MCP guide explains the same basic protocol from the local language-model side. For more local services on Windows, see the LocalAI Docker setup.
If the MCP layer is not what you need and you simply want a recent image workflow, the MiniMax H3 ComfyUI guide for Windows is the more direct route. You can also browse the site’s AI guides for the rest of the local stack.
Frequently asked questions
Is Comfy MCP free?
The PyPI package can be installed without a purchase, and normal local workflows do not require Comfy credits. Its source is licensed under AGPL-3.0-or-later or a separate Comfy commercial licence. Optional partner API nodes can use hosted services and spend credits.
Does Comfy MCP work offline?
It can control a local ComfyUI workflow, but the complete setup is only offline if the workflow, models and custom nodes make no external calls. Partner API nodes are online by definition.
Does the MCP server start ComfyUI automatically?
Not just because the server starts. Launch ComfyUI with comfy launch, or explicitly ask the agent to use the launch_comfyui tool.
Do I need a GPU?
Not for the MCP protocol itself. The ComfyUI workflow determines the hardware requirement. Lightweight or hosted workflows have different needs from a large local image or video model.
Can I use another MCP client?
Yes, provided the client supports local stdio MCP servers. Use comfy-mcp as the command and provide COMFY_BIN when the client cannot find the comfy executable. The exact settings screen varies by client.
Should I use the beta in a production workflow?
Treat it as a beta: record the versions you installed, keep a known-good workflow, require approval for consequential actions and retest after upgrades. The core workflow has been validated by the project, but the public API and tool behaviour may still change.
The practical verdict
Comfy MCP is worth trying if you already use ComfyUI and want an agent to handle the repetitive control work around known workflows. The cleanest setup is a dedicated Python environment, absolute executable paths, a small trusted test graph and an explicit approval step before execution.
The technology is young, so I would not hand it a directory full of private projects and tell it to improvise. Start with one workflow you understand. Once the validation, run and output loop is predictable, expand the agent’s access deliberately.