> ## Documentation Index
> Fetch the complete documentation index at: https://docs.comfy.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Comfy Local MCP

> Drive your own local ComfyUI from AI agents (Claude Code, Claude Desktop, Cursor) with the first-party comfy-local-mcp server — run workflows, collect outputs, and inspect the nodes and models your install actually has.

<Warning>
  **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.
</Warning>

[**comfy-local-mcp**](https://github.com/Comfy-Org/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](https://github.com/Comfy-Org/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](/agent-tools/cloud).

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](https://github.com/Comfy-Org/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](https://github.com/Comfy-Org/comfy-local-mcp):

```bash theme={null}
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.

<Note>
  **`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.
</Note>

***

## 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:

```bash theme={null}
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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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):

```json theme={null}
{
  "mcpServers": {
    "comfy-local": {
      "command": "comfy-local-mcp",
      "env": { "COMFY_BIN": "/path/to/venv/bin/comfy" }
    }
  }
}
```

***

## Quickstart

Zero to a generated image:

<Steps>
  <Step title="Install the pieces">
    ```bash theme={null}
    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
    ```
  </Step>

  <Step title="Launch ComfyUI and leave it running">
    ```bash theme={null}
    comfy launch
    ```
  </Step>

  <Step title="Add the server to your client">
    Use the snippet for your client above, then restart / reload it so the tools appear.
  </Step>

  <Step title="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.
  </Step>
</Steps>

***

## Tools

Each tool maps onto a `comfy-cli` command, run with `--where local`. Highlights:

| Tool                                        | Purpose                                                                          |
| ------------------------------------------- | -------------------------------------------------------------------------------- |
| `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_job` | Poll, 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_comfyui`           | Start or stop the local ComfyUI.                                                 |
| `search_templates` / `fetch_template`       | Find a built-in template and write its runnable workflow JSON.                   |
| `search_nodes` / `get_node` / `list_nodes`  | Inspect the node classes in your **live local** install (custom nodes included). |
| `search_models`                             | List the model files on disk.                                                    |
| `validate_workflow`                         | Pre-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](https://github.com/Comfy-Org/comfy-local-mcp) for the full tool list and reference.

***

## Related

* [Comfy Cloud MCP](/agent-tools/cloud) — hosted MCP server, no local install or GPU needed
* [Comfy Partner MCP](/agent-tools/partner-mcp) — local server for 30+ partner providers via the Comfy API
* [Comfy CLI](/agent-tools/comfy-cli) — drive local ComfyUI and partner generation from the terminal
* [comfy-local-mcp on GitHub](https://github.com/Comfy-Org/comfy-local-mcp) — source, install, and tool reference