# comfyui-mcp

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Python >=3.11](https://img.shields.io/badge/python-≥3.11-blue.svg)](https://www.python.org/)

通过 [MCP (Model Context Protocol)](https://modelcontextprotocol.io) 协议调用 [ComfyUI](https://github.com/comfyanonymous/ComfyUI)，加载并执行 workflow：文生图、图编辑、放大、去背景等。适用于 opencode、Claude Code、Cursor 等 MCP 客户端。

---

## 快速启动

```bash
uvx --from git+https://github.com/bookandmusic/comfyui-mcp.git comfyui-mcp \
    --comfyui.host 127.0.0.1:8188
```

首次运行自动下载依赖并创建隔离虚拟环境。5 个内置 workflow 开箱即用，无需额外配置。

---

## 工具列表

### 内置 workflow（`bundled_` 前缀）

| 工具名 | 说明 |
|---|---|
| `bundled_sensenova_json` | Sensenova 文生图 |
| `bundled_image_z_image_turbo_json` | Z-Image Turbo 文生图 |
| `bundled_qwen_image_2512_with_lora_json` | Qwen-Image-2512 + LoRA 文生图 |
| `bundled_utility_birefnet_remove_background_json` | BiRefNet 去背景 |
| `bundled_utility_z_image_turbo_2k_upscaler_json` | Z-Image Turbo 2K 放大 |

### 附加工具

| 工具名 | 说明 |
|---|---|
| `reboot_comfyui` | 重启 ComfyUI 服务，等待恢复后返回成功消息 |

### 本地 workflow

放入 `--comfyui.workflow_directory` 的 `.json` 文件会自动注册为工具，工具名为文件名中的 `.` 替换为 `_`，例如 `my_workflow.json` → `my_workflow`。

### 各工具共有参数

| 参数 | 类型 | 说明 |
|---|---|---|
| `prompt` | string | 图像描述（非必填，由具体 workflow 决定） |
| `seed` | int | 随机种子，留空自动生成。多批时自动递增 |
| `batch_by_time` | bool | 按时间轮询（分钟），与 `submit_batch` 配合 |
| `submit_batch` | int | 重复执行次数，或 `batch_by_time=true` 时的轮询分钟数 |
| `output_dir` | string | 可选，本地目录。提供时将结果图片下载到此目录并返回 Markdown 图片链接 |

---

## 配置

comfyui-mcp 的所有配置通过命令行参数传入，不支持配置文件。启动参数如下：

### 启动参数

| 参数 | 默认值 | 说明 |
|---|---|---|
| `--comfyui.host` | `$COMFYUI_HOST` 或 `127.0.0.1:8188` | ComfyUI 服务的 host:port |
| `--comfyui.workflow_directory` | `~/.config/comfyui-mcp/workflows` | 本地工作流目录（sync 时也作为下载目标） |
| `--comfyui.additional_workflow_directories` | `[]` | 额外工作流目录列表 |
| `--comfyui.sync_from_comfyui` | `false` | 启动时从 ComfyUI 同步所有 `.json` 到本地 |
| `--comfyui.request_timeout` | `30` | HTTP 请求超时（秒） |
| `--comfyui.max_retries` | `5` | 失败重试次数 |
| `--comfyui.queue_check_interval` | `2.0` | 队列轮询间隔（秒） |
| `--comfyui.max_wait_time` | `None` | 任务最长等待时间（秒，`None`=无限） |
| `--comfyui.reboot_timeout` | `300` | `reboot_comfyui` 工具等待恢复时间（秒） |

### Workflow 来源（按优先级）

**1. 内置 workflow**

随 wheel 打包，始终加载。工具名带 `bundled_` 前缀，不与用户 workflow 冲突。

**2. 本地目录**

`--comfyui.workflow_directory` 指定的目录（默认 `~/.config/comfyui-mcp/workflows/`）。放入 `.json` 文件，重启后自动注册。目录不存在时自动创建。

```bash
cp my-workflow.json ~/.config/comfyui-mcp/workflows/
```

需要多个目录时：

```bash
--comfyui.additional_workflow_directories '["/path/to/dir1", "/path/to/dir2"]'
```

**3. 从 ComfyUI 同步（可选）**

`--comfyui.sync_from_comfyui true` 启动后，MCP 调用 ComfyUI 的 `/api/v2/userdata` 列出所有 `.json` 文件并下载到本地 `workflow_directory`。适用于集中式 workflow 库 + 多 MCP 实例、跨机部署等场景。

```bash
uvx --from git+https://github.com/bookandmusic/comfyui-mcp.git comfyui-mcp \
    --comfyui.host 127.0.0.1:8188 \
    --comfyui.sync_from_comfyui true
```

> 注意：同步范围包括 userdata 下所有 `.json`（含非 workflow 的配置如 `styles.json`），缺少 `nodes` 字段的文件会报加载错误但不中断启动。

---

## 客户端配置

### opencode

```json
{
  "mcp": {
    "comfyui": {
      "type": "local",
      "command": [
        "uvx",
        "--from", "git+https://github.com/bookandmusic/comfyui-mcp.git",
        "comfyui-mcp",
        "--comfyui.host", "127.0.0.1:8188"
      ],
      "enabled": true,
      "timeout": 600000
    }
  }
}
```

### Claude Code

添加到 `~/.claude/settings.json`：

```json
{
  "mcpServers": {
    "comfyui": {
      "command": "uvx",
      "args": [
        "--from", "git+https://github.com/bookandmusic/comfyui-mcp.git",
        "comfyui-mcp",
        "--comfyui.host", "127.0.0.1:8188"
      ]
    }
  }
}
```

也可放在项目级 `.claude/settings.local.json` 中。

---

## 本地开发

```bash
git clone https://github.com/bookandmusic/comfyui-mcp.git
cd comfyui-mcp
uv sync
uv run python -m comfyui_mcp.server --comfyui.host 127.0.0.1:8188
```

或安装为本地命令：

```bash
uv tool install .
comfyui-mcp --comfyui.host 127.0.0.1:8188
```

---

## License

MIT — 详见 [LICENSE](./LICENSE)。