artokun/comfyui-mcp · 上手攻略
- 仓库：
artokun/comfyui-mcp - 链接：https://github.com/artokun/comfyui-mcp
- 分类：ComfyUI / MCP / 本地 Agent 控制面
- 作者：spark
- 更新：2026-08-31
数据速览（截至 2026-08-30 GitHub 公开计数）：592 stars · 91 forks · 2 watchers · MIT 许可。
⚠️ 数量版本漂移说明：README 自报"38 MCP tools / 42 AI skills / 56 installer packs"，GitHub 仓库 About 描述当前展示为"178 tools, 36 AI skills, 55 installer packs"——两个数字对不上。本文按 GitHub About 区当前描述为准（178 / 36 / 55），用 README 数据时显式标 ⚠️。
一、是什么
comfyui-mcp 是一个本地优先的 ComfyUI 控制面。它由两部分组成：
- 一个 MCP 服务器（stdio / Streamable-HTTP 两种 transport），把 ComfyUI 的能力（生成图、视频、音频、编辑 graph、安装节点、查模型、写 workflow）暴露成工具；
- 一个侧边栏 Agent（ComfyUI Agent Panel），嵌入在 ComfyUI 侧边栏，可以自然语言直接编辑你正在编辑的 live graph。
后端 LLM 完全可选：Claude 或 ChatGPT 用你的订阅，Gemini 用你的 Google 登录，本地 Ollama 离线跑，任何 OpenAI 兼容端点（DeepSeek / GLM / MiMo / Kimi / GPT / Claude via OpenRouter）一把 API key。
二、解决什么问题
已有 ComfyUI 但 LLM 想"操作"它的痛点：
- 大多数 MCP-ComfyUI 桥只是把 prompt 转给 ComfyUI 拿图回去。
comfyui-mcp是完整控制面：节点级编辑、workflow 编排、模型管理、custom node 安装 - 每次换模型（Flux / WAN / LTX 2.3 / MiniMax H3 / Qwen / Z-Image / Ideogram 4 / ERNIE / ANIMA…）都要重新学 sampler / CFG / 分辨率 / LoRA 路径——
comfyui-mcp把这些沉淀成 36 个 AI skill - 想让同一个 agent 跨本机 / RunPod / LAN / Comfy Cloud 跑——一个 config 搞定
- 想让 Claude 或 ChatGPT 在不暴露服务器的前提下远程操控——
--tunnel起一个 cloudflared quick tunnel，token 鉴权
三、快速安装
前置：Node.js ≥ 22（GitHub README 标
>=22.0.0），已安装 ComfyUI。
1. 加到 Claude Code（最常见路径）
编辑 ~/.claude/settings.json：
{
"mcpServers": {
"comfyui": {
"command": "npx",
"args": ["-y", "comfyui-mcp"],
"env": {
"CIVITAI_API_TOKEN": ""
}
}
}
}
不用 git clone——npx 会自己拉最新包跑。
2. 安装为 Claude Code 插件（带 slash command + skill + agent + hook）
/plugin marketplace add artokun/comfyui-mcp
/plugin install comfy
3. 装 ComfyUI Agent Panel（侧边栏）
ComfyUI-Manager 里搜 comfyui-agent-panel 直接装，或从 Comfy Registry 装。
4. 跑起来
启动 ComfyUI 后，对 Claude 说：
> Generate an image of a sunset over mountains
Claude 会自动找（或下载）checkpoint、构图、执行、返回图。
5. 远程 / 公开 URL 模式（Streamable-HTTP）
npx -y comfyui-mcp@latest --tunnel
输出形如 https://<random>.trycloudflare.com/mcp + token + Claude Desktop connector 片段。可贴给任何支持 Streamable-HTTP 的 MCP 客户端（含 Comfy Cloud 自家的 cloud.comfy.org/mcp）。
四、核心用法
1. 关键 MCP 工具节选
仓库 About 区自报 178 个 MCP 工具，覆盖：workflow 队列、历史、节点级编辑、checkpoint / LoRA / VAE 管理、custom node 安装 / 卸载 / 重启、图渲染 + 进度、模型搜索 / 下载 / Civitai 集成、生成历史 / gallery、/system_stats 系统监控。
2. 11 个 Slash Commands
| 命令 | 作用 |
|---|---|
/comfy:gen <prompt> |
文生图，自动选 checkpoint + 构图 |
/comfy:viz <workflow> |
把 workflow 渲染成 Mermaid 节点分组图 |
/comfy:node-skill <pack> |
从 Registry ID / GitHub URL 生成 claude skill |
/comfy:debug [prompt_id] |
读 history + log，定位失败节点 + 修 |
/comfy:batch |
cfg / sampler / steps / seed 参数扫描 |
/comfy:convert <file> |
UI ↔ API workflow 互转 |
/comfy:install <pack> |
安装 custom node pack |
/comfy:gallery [filter] |
按时间 / 数量 / 文件名浏览输出 |
/comfy:compare <a vs b> |
workflow 差异 diff |
/comfy:recipe <name> <prompt> |
多步配方：portrait / hires-fix / style-transfer / product-shot |
3. 36 个 AI Skills（README 自报 42，按 GitHub About 当前 36 取值）
按模型家族分组：Flux / WAN / LTX 2.3 / MiniMax H3 / Qwen / Z-Image / Ideogram 4 / ERNIE / ANIMA / anime / WAN / Z-Image LoRA 训练 + 模型 registry + Civitai 配对 + 节点自写作 + 启动 / 性能 flag 矩阵。
核心 4 件：
| Skill | 用途 |
|---|---|
| comfyui-core | workflow 格式 / 节点类型 / 数据流 / pipeline 架构 / MCP 工具使用 |
| prompt-engineering | CLIP 权重语法 (word:1.3) / BREAK token / embeddings / 模型专属 prompt（SD1.5 / SDXL / Flux / SD3） |
| troubleshooting | 错误目录（OOM / dtype / 缺节点 / NaN / 黑图 / CUDA 错）+ VRAM 估计 |
| model-compatibility | 兼容性矩阵：loader / 分辨率 / CFG / sampler / ControlNet / LoRA / VAE × SD1.5 / SDXL / Turbo / Lightning / Flux / SD3 / LTXV |
4. 4 个 Autonomous Agents（全 Sonnet）
| Agent | 作用 |
|---|---|
| comfy-explorer | 调研 custom node pack——读文档、/object_info、生成 skill 文件 |
| comfy-debugger | 自动诊断 workflow 失败——拉日志 + history，定位失败节点，给修复建议 |
| comfy-optimizer | 性能优化——冗余节点、VRAM 浪费、CFG / steps / precision 不当 |
| comfy-researcher | 给定图像生成问题，推荐 + 排名 custom node pack |
5. 3 个 Hooks
| 事件 | 触发 | 动作 |
|---|---|---|
| PreToolUse | enqueue_workflow |
VRAM watchdog——执行前查 /system_stats，<1 GB 报警 |
| PreToolUse | restart_comfyui（stop/restart） |
保存提示——阻止前确认 unsaved workflow 已保存 |
| PostToolUse | 任何 comfyui tool | 完成通知——注入完成摘要到对话 |
6. 55 个 Installer Packs（README 自报 56，按 GitHub About 当前 55 取值）
packs/ 一键装：ANIMA / Ideogram 4 / LTX-2.3 / ERNIE / WAN（animate / longer-videos / transparent）/ Qwen（image / image-edit）/ Z-Image（turbo / base / xy-plot）/ artokun-flow（WAN Animate：replace / animate）。每个是"custom node + 模型 URL + workflow"清单，可驱动 apply_manifest 和 install-windows.bat / install-runpod.sh，CI 校验每个模型链接 + payload size。
7. connect：从本机驱动远程 ComfyUI
# 远端 ComfyUI（RunPod / VPS）跑着，本机 Claude / ChatGPT 登录驱动它
npx -y comfyui-mcp@latest connect https://abcd1234-3000.proxy.runpod.net
远端 pod 不装任何 agent、不暴露端口；本机起 connect，开 cloudflared wss:// tunnel 给 pod 的面板用。
五、典型适用场景
- 已有 ComfyUI 工作流，想用 Claude / ChatGPT / Gemini 直接编辑或扩展它
- 经常跨模型实验（每天 Flux → WAN → LTX-Video 切），不想每次重学 sampler / 分辨率
- RunPod / VPS 跑 ComfyUI，本机订阅 Claude / ChatGPT 想直接驱动
- 想给团队配一套"AI 辅助 ComfyUI"——
--tunnel+ token 鉴权就能分享 - 不想自己装 ComfyUI——一键 RunPod template
bnqtkvcer3（README 标注）预装好 ComfyUI + Agent Panel + ComfyUI-Manager v2
六、坑与注意
- ⚠️ 数字漂移：仓库 About 区与 README 数字不一致（178/36/55 vs 38/42/56）——按 About 当前值取，README 数据显式标 ⚠️
- ⚠️ Comfy Cloud 用户有另一条路：Comfy-Org 自己出了 agent tooling（Cloud MCP / In-App Agent / Local MCP），状态 2026-07 截取时为 public beta / private alpha / private test。如果"不想自己装 GPU、零配置"是首选，那条路更合适；本仓库的差异化是"装在你自己的 ComfyUI + 你自己的模型"
--tunnel用 cloudflared quick tunnel 是临时的；要稳定子域名得自己接 Cloudflare 账号connect用 cloudflared wss:// tunnel 给远程 ComfyUI 用，会跨 cloudflared 网络中转——敏感工作流慎用公开隧道- 55 个 installer pack 的模型 URL 都是远端下载；CI 校验"链接 200 + payload size 正常"，但模型实际可用性 / 许可证仍需自审
- Hook 触发的是 Claude Code 行为——如果你用其他 MCP 客户端（如 Cursor / Gemini CLI），hook 不生效
- OAuth（Comfy 浏览器登录流）是 README 的"planned follow-up"——目前 auth 仅有
Authorization: Bearer <token>或X-API-Key: <token>，沿用 Comfy Cloud 约定
七、与同类对比
| 维度 | comfyui-mcp | Comfy-Org Cloud MCP | 简易桥（多数其他 MCP-ComfyUI 项目） |
|---|---|---|---|
| 部署 | 本地 / LAN / VPS / Comfy Cloud 一键 --tunnel |
仅 Comfy Cloud | 一般仅本地 |
| LLM 后端 | 任意（Claude / ChatGPT / Gemini / Ollama / OpenAI 兼容） | Comfy Cloud 平台托管 | 一般绑 Claude |
| 工具深度 | 178 个 MCP 工具，含节点级 graph 编辑 | 平台托管 agent（in-app / cloud） | 多为 prompt → image 单步 |
| 模型专业知识 | 36 个 AI skill，按模型家族沉淀 | 平台内置 | 多依赖 prompt 试错 |
| 离线能力 | 是（Ollama + 本地 ComfyUI） | 否（依赖云） | 一般否 |
| 侧边栏 agent | 是（ComfyUI Agent Panel） | 是（In-App Agent，private alpha） | 否 |
八、一句话推荐结论
如果你已有 ComfyUI、想用任何 LLM（订阅 / 本地 / API）直接编辑 live graph 并按模型家族获得专业知识——comfyui-mcp 是当下能力最深、跨部署形态最完整的一个本地控制面；Comfy Cloud 用户则该先去 docs.comfy.org/agent-tools 看看平台自带 agent 的状态。