# comfyui-mcp-server

一个 MCP（Model Context Protocol）服务器，让 Agent 通过 MCP 工具直接驱动本地
[ComfyUI](https://www.comfy.org/) 实例，专注于 **MiniMax H3** 视频生成工作流
（文生视频 / 图生视频 / 参考生视频 / 多帧参考）。

## 它解决什么问题

ComfyUI 的 `/prompt` 接口只接受 **API 格式** 的工作流，但我们在 UI 里保存的
工作流是 **UI 格式**（`nodes[] + links[] + definitions.subgraphs`，并用 subgraph
封装节点）。本服务器：

- 列出 / 读取本地 ComfyUI 已保存的 UI 格式工作流
- 自动把 UI 格式（含 subgraph 封装）**展平** 成 API 格式
- 提交任务、轮询进度、下载产物（mp4）
- 上传参考图（图生视频 / 参考生视频用）

## 提供的工具

| 工具 | 说明 |
| --- | --- |
| `comfy_status` | 检查 ComfyUI 服务状态（版本、GPU/显存、队列） |
| `comfy_list_workflows` | 列出已保存的工作流 |
| `comfy_get_workflow` | 读取工作流结构摘要（节点类型、提示词节点、可调参数） |
| `comfy_generate_video` | 生成视频（覆盖 prompt / duration / 比例 / 参考图 / 自定义 overrides） |
| `comfy_get_result` | 按 `prompt_id` 查询执行结果与输出文件 |
| `comfy_queue_status` | 查看当前运行 / 等待队列 |
| `comfy_list_objects` | 查询已安装节点类型及其输入参数 |
| `comfy_list_models` | 列出本机已安装模型文件 |

## 安装

```bash
npm install
```

依赖：`@modelcontextprotocol/sdk`、`zod`。

## 配置（环境变量）

| 变量 | 默认值 | 说明 |
| --- | --- | --- |
| `COMFY_HOST` | `http://localhost:8188` | ComfyUI 服务地址 |
| `COMFY_WORKFLOW_DIR` | `<项目>/workflows` | UI 工作流存放目录 |
| `COMFY_OUT_DIR` | `<项目>/outputs` | 产物下载目录 |
| `COMFY_CLIENT_ID` | `agent-<timestamp>` | 客户端标识 |

## 自测

```bash
node selftest.mjs
```

会通过 stdio 协议完成握手，并依次调用 `comfy_status` / `comfy_list_workflows` /
`comfy_get_workflow` / `comfy_queue_status`，最后提交一个 2 秒低分辨率 t2v 任务。

## 接入（以 Claude Desktop / WorkBuddy 为例）

在 MCP 配置中加入：

```json
{
  "mcpServers": {
    "comfyui": {
      "command": "node",
      "args": ["/绝对路径/comfyui-mcp-server/index.js"],
      "env": {
        "COMFY_HOST": "http://localhost:8188"
      }
    }
  }
}
```

## 许可证

MIT