# ComfyUI MCP Server

[中文](./README.md) | [English](./README_EN.md)

把 ComfyUI App Mode 工作流包装成 MCP 工具，让 AI 助手可以像调用普通工具一样查询模板、执行工作流、串联多步生成，并处理图片等媒体结果。

如果有 BUG 或想要的功能，可以加群 `1082160486` 或提 issue。

## 适合什么场景

- **给 AI 暴露 ComfyUI 能力**：AI 只需要填写模板参数，不需要理解节点图。
- **复用 App Mode 工作流**：用 ComfyUI 前端标记输入、输出，再生成 MCP 模板。
- **批量与多步执行**：一次调用可运行多个独立任务，也可把前一步输出继续交给下一步处理。
- **查询本地模型**：支持让 AI 查询 `checkpoints`、`loras`、`vae` 等模型目录。

## 快速开始

1. 安装插件（二选一）：
    - **通过 ComfyUI Manager 安装（推荐）**：打开 ComfyUI Manager，搜索 `app mode mcp`，点击安装。
    - **通过 Git 安装**：把仓库克隆到 ComfyUI 的 `custom_nodes` 目录：

        ```bash
        cd ComfyUI/custom_nodes
        git clone https://github.com/Luo-Lotus/ComfyUI-APP-MCP.git
        cd ComfyUI-APP-MCP
        # 请使用实际启动 ComfyUI 的 Python；虚拟环境需先激活
        python -m pip install -r requirements.txt
        ```

        Windows 便携包请在 `ComfyUI_windows_portable` 目录使用包内的 Python 安装依赖：

        ```powershell
        .\python_embeded\python.exe -m pip install -r .\ComfyUI\custom_nodes\ComfyUI-APP-MCP\requirements.txt
        ```

2. 启动或重启 ComfyUI，并确保使用支持 App Mode 的版本。
3. 打开工作流，在左上角菜单进入 **App Builder**。
4. 标记希望 AI 修改的内容为输入，标记保存图片等节点为输出，并把输入命名成清晰参数名。
5. 添加 Markdown Note 说明模板：
    - `title`：模板短标题，显示在模板列表中
    - `description`：模板详细说明，显示在模板详情中
    - 其他标题：作为可按需读取的模板文档

6. 在 **Settings → MCP Server → Templates** 点击 **Create from Workflow** 创建模板。
7. 在 MCP 客户端连接 `http://127.0.0.1:<ComfyUI 端口>/app-mcp` 或 `http://127.0.0.1:8189/mcp`。
8. 让 AI 先调用 `list_templates()`，再调用 `get_template()`、`run_template()` 或 `run_templates()`。

工作流变更后，在设置面板对同名模板点击 **Refresh**。如果输入参数发生变化，提醒 AI 重新读取模板。

如果希望每次运行自动随机 seed，把 App Builder 中对应输入命名为 `seed`。运行时会自动填入随机值，AI 不需要传这个参数。

## 连接地址

| 入口             | 地址                                      | 说明                                |
| ---------------- | ----------------------------------------- | ----------------------------------- |
| ComfyUI 代理入口 | `http://127.0.0.1:<ComfyUI 端口>/app-mcp` | 通过 ComfyUI 端口访问 MCP           |
| MCP 直接入口     | `http://127.0.0.1:8189/mcp`               | 随 ComfyUI 一起启动，和上面用法一致 |

MCP 客户端配置示例：

```json
{
    "mcpServers": {
        "comfyui": {
            "url": "http://127.0.0.1:<ComfyUI 端口>/app-mcp"
        }
    }
}
```

也可以把 `url` 换成：

```text
http://127.0.0.1:8189/mcp
```

远程访问 ComfyUI 时，使用 `python main.py --listen` 启动。

局域网或远程访问时，把 `127.0.0.1` 换成实际 ComfyUI/MCP 机器地址。更多部署方式见 [独立部署与远程访问](./docs/zh/standalone.md)。

## 常用工具

| 工具                             | 用途                             | 什么时候用                           |
| -------------------------------- | -------------------------------- | ------------------------------------ |
| `list_templates()`               | 查看可用模板                     | 开始任务前先查有哪些能力             |
| `get_template(name)`             | 读取模板参数、输出、文档入口     | 执行前确认参数怎么填                 |
| `read_template_doc(name, title)` | 读取模板的扩展说明               | `description` 提到更多文档时使用     |
| `run_template()`                 | 执行单个模板                     | 文生图、图生图、放大、加密等单步任务 |
| `run_templates()`                | 一次运行多个任务并返回每一步结果 | 批量生成，或生成 → 放大等多步处理    |
| `upload_image(source)`           | 上传用户提供的新图片             | 图片来自用户本地、URL 或 base64 时   |
| `list_models(folder, keywords)`  | 查询模型目录                     | 需要选择 checkpoint、LoRA、VAE 时    |
| `get_template_result()`          | 查询或继续等待结果               | `run_template` 超时或异步等待时      |

完整参数、返回结构和示例见 [工具参考](./docs/zh/tools.md)。

## 前端管理

在 **Settings → MCP Server** 中可以：

- 设置 `run_template(wait=true)` 默认等待超时
- 配置模板执行令牌、最大使用次数和有效时间
- 创建、刷新、启用、禁用、删除模板
- 扫描工作流并自动创建缺失模板
- 批量刷新已有模板
- 导出模板 zip，用于独立部署

更多说明见 [工具参考：前端管理](./docs/zh/tools.md#comfyui-前端管理)。

## 文档导航

| 文档                                          | 内容                                                 |
| --------------------------------------------- | ---------------------------------------------------- |
| [工具参考](./docs/zh/tools.md)                | MCP 工具参数、返回格式、模板串联、上传图片、模型查询 |
| [独立部署与远程访问](./docs/zh/standalone.md) | 环境变量、独立配置、媒体代理、客户端连接             |
| [故障排查](./docs/zh/troubleshooting.md)      | 模板为空、输出为空、图片输入、远程访问、日志         |
| [开发说明](./docs/zh/development.md)          | 代码结构、测试建议、开发命令                         |
| [文档索引](./docs/README.md)                  | 中英文文档入口                                       |

## 最常见问题

### 创建模板时找不到工作流

插件模式会自动读取 ComfyUI 的实际启动端口，使用自定义端口时无需额外配置。如果需要覆盖自动检测的地址，可在启动前设置：

```bash
COMFYUI_URL=http://<ComfyUI 主机>:<端口>
```

### AI 填入的输入字段不生效

确保 AI 传入的参数名与 `get_template()` 返回的模板参数完全一致。

不要把节点的自定义 UI 选项直接标记为输入，AI 无法识别这类选项。可以尝试把自定义 UI 上方的数据内容输入框标记为输入；该输入框通常保存了自定义 UI 中选择的实际数据。确认其中的数据格式后，在模板的 `description` 中说明字段结构和填写方法，让 AI 按要求传入。

### 接入 AstrBot 等平台后图片发不出来

检查 App Builder 中的输入、输出节点是否配置完整，尤其要确保输出节点中包含保存图片节点。

确认 AI 调用平台发送工具时参数类型正确。常见错误是把图片 URL 填到 `path` 这类本地文件路径参数里；如果平台工具区分 `url`、`image_url`、`file`、`path`，应按工具要求传对应字段。

更多排查方式见 [故障排查](./docs/zh/troubleshooting.md)。