Skip to main content
Early preview. comfy-local-mcp is an early proof-of-concept. The core loop (server_info → run_workflow → fetch_outputs) is validated end-to-end against a live local ComfyUI, but tools and behavior may still change.
comfy-local-mcp is Comfy’s first-party local MCP server — the official way to drive a local ComfyUI install from AI agents (Claude Code, Claude Desktop, Cursor, and other MCP clients). It is a thin wrapper over comfy-cli: each tool shells out to the comfy command, so comfy-cli is the engine and there is no code shared with the Comfy Cloud MCP. Unlike the cloud and partner servers, it talks to the ComfyUI running on your own machine — so it can run your workflows and inspect the nodes, custom nodes, and models your install actually has.

​
Requirements

  • Python 3.10+
  • comfy-cli on your PATH (pip install comfy-cli) — the engine every tool wraps
  • A ComfyUI workspace — create one with comfy install if you don’t have one (an existing checkout works via comfy set-default <path>)
  • A running ComfyUI — start it with comfy launch before using the tools; nothing here launches ComfyUI implicitly

​
Installation

From a checkout of the repository: 
pip install .        # or `pip install -e .` for a working copy
This puts a comfy-local-mcp console script on your PATH — that command is the MCP server (it speaks MCP over stdio). Point your AI client at it below.
COMFY_BIN (optional). MCP clients launch the server with their own environment, which often does not include your shell’s PATH. If comfy lives in a virtualenv or a non-standard location, set COMFY_BIN to its absolute path (for example /path/to/venv/bin/comfy). Every client example below shows where it goes; drop it if comfy is already on the environment your client launches the server with.

​
Configure your AI client

All clients speak the same MCP stdio contract: run the comfy-local-mcp command as a server. Pick your client.

​
Claude Code

One command registers the server: 
claude mcp add comfy-local -e COMFY_BIN=/path/to/venv/bin/comfy -- comfy-local-mcp
Or check it into a project with a .mcp.json at the repo root: 
{
  "mcpServers": {
    "comfy-local": {
      "command": "comfy-local-mcp",
      "env": { "COMFY_BIN": "/path/to/venv/bin/comfy" }
    }
  }
}

​
Claude Desktop

Edit claude_desktop_config.json (Settings → Developer → Edit Config; on macOS it lives at ~/Library/Application Support/Claude/claude_desktop_config.json), add the server, then restart Claude Desktop: 
{
  "mcpServers": {
    "comfy-local": {
      "command": "comfy-local-mcp",
      "env": { "COMFY_BIN": "/path/to/venv/bin/comfy" }
    }
  }
}

​
Cursor

Add the server to ~/.cursor/mcp.json (global) or .cursor/mcp.json (per project): 
{
  "mcpServers": {
    "comfy-local": {
      "command": "comfy-local-mcp",
      "env": { "COMFY_BIN": "/path/to/venv/bin/comfy" }
    }
  }
}

​
Quickstart

Zero to a generated image:
1

Install the pieces

pip install comfy-cli     # the engine
comfy install             # create a ComfyUI workspace (skip if you have one)
pip install .             # this MCP server → the `comfy-local-mcp` command
2

Launch ComfyUI and leave it running

comfy launch
3

Add the server to your client

Use the snippet for your client above, 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 the workflow JSON, and fetch_outputs to collect the result.

​
Tools

Each tool maps onto a comfy-cli command, run with --where local. Highlights:
ToolPurpose
server_info()Is a local ComfyUI running, where, and which workspace. Call first.
run_workflow(workflow_path, wait=True)Run a workflow JSON; wait=False submits async and returns a prompt_id.
job_status / wait_for_job / watch_jobPoll, wait on, or stream a submitted job.
fetch_outputs(prompt_id, out_dir)Copy a finished job’s outputs into out_dir.
launch_comfyui / stop_comfyuiStart or stop the local ComfyUI.
search_templates / fetch_templateFind a built-in template and write its runnable workflow JSON.
search_nodes / get_node / list_nodesInspect the node classes in your live local install (custom nodes included).
search_modelsList the model files on disk.
validate_workflowPre-flight a workflow against the live object_info before a slow run.
Node introspection and model search read your live install — custom nodes included — which is the local differentiator from the cloud MCP. See the repository for the full tool list and reference.