DEV Community

Lachlan Dromgold
Lachlan Dromgold

Posted on • Originally published at lachieslifestyle.com

Install Comfy MCP: Control Local ComfyUI from Claude Code or Cursor

#ai #mcp #tutorial #comfyui

Comfy MCP is Comfy's first-party local Model Context Protocol server. It lets an MCP-capable coding agent inspect the models and nodes in your ComfyUI installation, validate workflows, run them, and retrieve the outputs.

The detail that prevents the most confusion is that two processes are involved:

  • comfy launch starts ComfyUI.
  • Your AI client starts comfy-mcp as a local stdio server.

If you run comfy-mcp directly and it appears to do nothing, it is probably waiting for an MCP client. That is normal for a stdio server.

Disclosure and verification scope: AI tools assisted with drafting and editing this adaptation. I reviewed the finished article and checked the commands and material claims 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 this is a documentation-verified setup guide, not a hands-on performance test. Comfy's documentation currently labels the MCP offering a public beta, so tools and behaviour may change.

What you need

Before starting, have:

  • Python 3.10 or newer. The examples below use Python 3.11.
  • comfy-cli 1.14.0 or newer.
  • A ComfyUI workspace, either created with comfy install or selected with comfy set-default.
  • An MCP client that can start a local stdio server, such as Claude Code, Cursor, or Claude Desktop.
  • The models and custom nodes required by the workflow you want to run.

The MCP bridge is not what determines the hardware requirement; the selected ComfyUI workflow does. A small image workflow and a large video workflow can have very different memory needs.

1. Install comfy-cli and comfy-mcp

I prefer a dedicated virtual environment. It keeps the executables in a predictable place and avoids mixing these packages with unrelated Python projects.

Windows PowerShell 

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 --version
Enter fullscreen mode Exit fullscreen mode

Keep the two paths printed by where.exe. You will use them in your MCP configuration.

If PowerShell blocks virtual-environment activation, you can use the environment's executables directly:

.\.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 --version
Enter fullscreen mode Exit fullscreen mode

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 --version
Enter fullscreen mode Exit fullscreen mode

Keep the absolute paths returned by command -v.

2. Create or select your ComfyUI workspace

For a new managed installation, run:

comfy install
Enter fullscreen mode Exit fullscreen mode

If ComfyUI is already installed, point comfy-cli at its directory:

# Windows example
comfy set-default "D:\AI\ComfyUI"
Enter fullscreen mode Exit fullscreen mode 
# macOS or Linux example
comfy set-default "/home/your-name/ComfyUI"
Enter fullscreen mode Exit fullscreen mode

Replace the example path with the real ComfyUI directory. Comfy's repository also warns macOS users that placing ComfyUI in Documents, Desktop, or Downloads can cause permission errors unless the MCP client has Full Disk Access.

3. Launch ComfyUI 

comfy launch
Enter fullscreen mode Exit fullscreen mode

Leave that process running. A normal local instance uses 127.0.0.1:8188.

The MCP server does not start ComfyUI merely because the server launches. An agent can invoke the separate launch_comfyui tool, but that must be an explicit action.

4. Connect Claude Code

Comfy's official quick-start registers a local server called comfy-mcp. Using absolute paths is more reliable than assuming the MCP client inherits the virtual environment from another 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.exe
Enter fullscreen mode Exit fullscreen mode

macOS 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-mcp
Enter fullscreen mode Exit fullscreen mode

Replace every sample path with the path from your machine.

COMFY_BIN is optional when the environment used by the client can already find comfy. I still set the absolute path because it removes an avoidable source of failures.

5. Connect Cursor or Claude Desktop

Both clients use an mcpServers object. Add the appropriate version to that client's MCP configuration, then fully restart the client.

Windows 

{
  "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"
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

macOS or Linux 

{
  "mcpServers": {
    "comfy-mcp": {
      "command": "/home/you/tools/comfy-mcp/.venv/bin/comfy-mcp",
      "env": {
        "COMFY_BIN": "/home/you/tools/comfy-mcp/.venv/bin/comfy"
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Cursor accepts this in ~/.cursor/mcp.json for a global configuration or .cursor/mcp.json for a project. Claude Desktop exposes its configuration through Settings → Developer → Edit Config.

After restarting, check the client's MCP or tools panel for comfy-mcp.

6. Validate a small workflow before running it

Start with a workflow you already understand, saved as ComfyUI API JSON or as a UI-exported workflow. A known graph makes MCP problems easier to separate from missing models and third-party custom nodes.

My preferred first prompt adds a review boundary:

Check my local ComfyUI server and validate the workflow at
C:/AI/workflows/txt2img.json. Report any missing nodes or models.
Do not run the workflow until I approve it.
Enter fullscreen mode Exit fullscreen mode

Once you approve the workflow, the main tool sequence is straightforward:

  1. server_info confirms the local instance and workspace.
  2. validate_workflow checks the graph against the live installation.
  3. run_workflow submits it.
  4. fetch_outputs retrieves the completed output.

MCP makes the workflow convenient, but it also gives an agent a capable local tool. Validation before execution is a sensible default.

Privacy and spending checks

"Local" does not automatically mean "offline." A local ComfyUI workflow can stay on your machine, but partner API nodes and third-party custom nodes may make network calls.

Before expanding the setup:

  • Keep ComfyUI bound to localhost unless you have a separate, secured remote-access design.
  • Review third-party workflows and custom nodes before running them.
  • Keep client approval prompts enabled for consequential actions.
  • Use an isolated ComfyUI workspace rather than handing the agent a directory full of unrelated private projects.
  • Add COMFY_API_KEY only if you intend to use partner API nodes. Those hosted services may consume credits.
  • Avoid putting secrets in launch arguments or file paths.

Comfy documents the following telemetry opt-out command:

comfy tracking disable
Enter fullscreen mode Exit fullscreen mode

That setting does not prevent partner nodes or custom nodes from making their own external requests.

Troubleshooting

comfy-mcp opens but prints nothing

That is expected when a stdio MCP server is started directly. Stop it with Ctrl+C, confirm the package with comfy-mcp --version, and let your MCP client launch it.

The client cannot find comfy or comfy-mcp

An MCP client often does not inherit the virtual environment activated in a different terminal. Put the full comfy-mcp path in command, put the full comfy path in COMFY_BIN, and restart the client.

The tools appear but cannot reach ComfyUI

Run comfy launch and check that the local instance is available at its expected address. Also confirm that comfy-cli points to the intended default workspace.

Windows reports invalid JSON

Backslashes must be escaped in JSON. Forward slashes in executable paths, as used above, are usually the easiest fix.

Every Comfy tool appears twice

Look for two MCP entries pointing at the same comfy-mcp command. Edit the existing entry instead of registering a second server under a different label.

The practical verdict

Comfy MCP is a useful fit if you already use ComfyUI and want an agent to handle the repetitive control work around known workflows. The least frustrating setup is a dedicated Python environment, absolute executable paths, a small trusted graph, and an explicit approval step before execution.

Start with one workflow you understand. Expand the agent's access only after the validation, run, and output loop behaves predictably.

Official sources

Top comments (1)

Collapse
 
daymondhyper profile image
DaymondHyper •

Bookmarked. The part about evaluation being mandatory is exactly what I keep missing in my own experiments. How do you measure regressions, a separate test set?