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

> 使用官方的 comfy-local-mcp 服务器，通过 AI 代理（Claude Code、Claude Desktop、Cursor）驱动你自己的本地 ComfyUI：运行工作流、收集输出，并检查你的安装实际拥有的节点和模型。

<Warning>
  **早期预览。** `comfy-local-mcp` 是一个早期的概念验证。核心循环（`server_info → run_workflow → fetch_outputs`）已针对运行的本地 ComfyUI 进行了端到端验证，但工具和行为可能仍会发生变化。
</Warning>

[**comfy-local-mcp**](https://github.com/Comfy-Org/comfy-local-mcp) 是 Comfy 的**第一方本地 MCP 服务器**：从 AI 代理（Claude Code、Claude Desktop、Cursor 及其他 MCP 客户端）驱动**本地** ComfyUI 安装的官方方式。它是在 [comfy-cli](https://github.com/Comfy-Org/comfy-cli) 之上的薄封装：每个工具都会调用外部的 `comfy` 指令，因此 `comfy-cli` 是引擎，并且与 [Comfy Cloud MCP](/zh/agent-tools/cloud) 没有共享任何代码。

与云端和合作伙伴服务器不同，它与运行在**您自己的机器**上的 ComfyUI 通信，因此它可以运行您的工作流，并检查您的安装实际拥有的节点、自定义节点和模型。

## 要求

* **Python 3.10+**
* **在您的 `PATH` 中的 [comfy-cli](https://github.com/Comfy-Org/comfy-cli)**（`pip install comfy-cli`）：每个工具所依赖的引擎
* **一个 ComfyUI 工作区**：如果您还没有，请使用 `comfy install` 创建一个（已有的检出可通过 `comfy set-default <path>` 来使用）
* **正在运行的 ComfyUI**：在使用工具之前，请用 `comfy launch` 启动它；此处的任何操作都不会隐式启动 ComfyUI

## 安装

从[仓库](https://github.com/Comfy-Org/comfy-local-mcp)的检出副本开始：

```bash theme={null}
pip install .        # 或 `pip install -e .` 以获得可编辑的副本
```

这会将一个名为 `comfy-local-mcp` 的控制台脚本添加到您的 `PATH` 中。该命令就是 MCP 服务器（它通过 stdio 使用 MCP 协议通信）。请按下方说明将其配置到您的 AI 客户端。

<Note>
  **`COMFY_BIN`（可选）。** MCP 客户端会在自己的环境中启动服务器，该环境通常**不**包含您 shell 环境中的 `PATH`。如果 `comfy` 位于虚拟环境或非标准位置，请将 `COMFY_BIN` 设置为其绝对路径（例如 `/path/to/venv/bin/comfy`）。下方的每个客户端示例都会说明其放置位置；如果 `comfy` 已存在于客户端用来启动服务器的环境中，则可以省略该设置。
</Note>

***

## 配置 AI 客户端

所有客户端均使用相同的 MCP stdio 协议：将 `comfy-local-mcp` 指令作为服务器运行。选择您的客户端。

### Claude Code

一条指令即可注册服务器：

```bash theme={null}
claude mcp add comfy-local -e COMFY_BIN=/path/to/venv/bin/comfy -- comfy-local-mcp
```

或者通过项目根目录下的 `.mcp.json` 文件将其纳入版本控制：

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

### Claude Desktop

编辑 `claude_desktop_config.json`（设置 → 开发者 → 编辑配置；macOS 上位于 `~/Library/Application Support/Claude/claude_desktop_config.json`），添加服务器，然后重新启动 Claude Desktop：

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

### Cursor

将服务器添加到 `~/.cursor/mcp.json`（全局）或 `.cursor/mcp.json`（按项目）：

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

***

## 快速入门

从零开始到已生成图像：

<Steps>
  <Step title="安装组件">
    ```bash theme={null}
    pip install comfy-cli     # 引擎
    comfy install             # 创建ComfyUI工作区（如果已有则跳过）
    pip install .             # 此MCP服务器 → `comfy-local-mcp`指令
    ```
  </Step>

  <Step title="启动ComfyUI并保持运行">
    ```bash theme={null}
    comfy launch
    ```
  </Step>

  <Step title="将服务器添加到客户端">
    使用上面适用于您客户端的代码片段，然后重新启动/重新加载它，以便工具出现。
  </Step>

  <Step title="让您的代理运行工作流">
    例如：

    > "确认我的本地ComfyUI正在运行，然后运行 `~/workflows/txt2img.json` 中的工作流并向我展示图像。"

    在底层，代理调用 `server_info` 确认ComfyUI已启动，调用 `run_workflow` 执行工作流JSON，并调用 `fetch_outputs` 收集结果。
  </Step>
</Steps>

***

## 工具

每个工具对应一个 `comfy-cli` 指令，使用 `--where local` 运行。主要工具如下：

| 工具                                          | 用途                                              |
| ------------------------------------------- | ----------------------------------------------- |
| `server_info()`                             | 检查本地 ComfyUI 是否正在运行、运行位置以及所属工作区。**请优先调用。**      |
| `run_workflow(workflow_path, wait=True)`    | 运行工作流 JSON；`wait=False` 时异步提交并返回一个 `prompt_id`。 |
| `job_status` / `wait_for_job` / `watch_job` | 轮询、等待或流式查看已提交的任务。                               |
| `fetch_outputs(prompt_id, out_dir)`         | 将已完成任务的输出复制到 `out_dir`。                         |
| `launch_comfyui` / `stop_comfyui`           | 启动或停止本地的 ComfyUI。                               |
| `search_templates` / `fetch_template`       | 查找内置模板并写入其可运行的工作流 JSON。                         |
| `search_nodes` / `get_node` / `list_nodes`  | 检查**本地实时安装**中的节点类（包括自定义节点）。                     |
| `search_models`                             | 列出磁盘上的模型文件。                                     |
| `validate_workflow`                         | 在慢速运行之前，针对实时的 `object_info` 预检工作流。              |

节点内省和模型搜索会读取您的**实时安装**（包括自定义节点），这是本地与云端 MCP 的差异所在。请参阅[仓库](https://github.com/Comfy-Org/comfy-local-mcp)获取完整工具列表和参考。

***

## 相关

* [Comfy Cloud MCP](/zh/agent-tools/cloud) — 托管MCP服务器，无需本地安装或GPU
* [Comfy Partner MCP](/zh/agent-tools/partner-mcp) — 通过Comfy API为30多家合作伙伴提供商提供的本地服务器
* [Comfy CLI](/zh/agent-tools/comfy-cli) — 从终端驱动本地ComfyUI和合作伙伴生成
* [comfy-local-mcp on GitHub](https://github.com/Comfy-Org/comfy-local-mcp) — 来源、安装和工具参考