ComfyUI 工具桥 Hyh0626/comfyui-agent-kit

comfyui-agent-kit

把全局 ComfyUI MCP server 同时接入 Codex / Claude Code / ZCode / DeepSeek Harness (DSH)。
同一个 comfyui-local server、同一组环境变量、同一套 19 个工具；四个智能体之间互不干扰。

English: One local MCP server that exposes ComfyUI's HTTP API plus SDXL LoRA
training as 19 tools, with registration snippets for Codex, Claude Code, ZCode and
DeepSeek Harness. The DSH side ships a Cordis plugin that turns the same tools into
native DSH tools.

为什么需要 DSH 插件

Codex / Claude Code / ZCode 都有自己的 MCP 客户端，注册一下就能直连 server.py。
DSH 的工具模型是 Cordis，没有外部 MCP 挂载机制，所以这里额外提供一个薄桥接插件 dsh-plugin/：启动时读一次 tools/list，把 19 个工具用 ctx.tools.register 注册成一等原生工具；每次调用再拉起短命 server.py 转发。

┌─ Codex （原生 MCP，TOML） server.py ◄────────┼─ Claude Code （原生 MCP，JSON） features.py ├─ ZCode （原生 MCP，JSON） │ 19 tools └─ DSH （Cordis 插件 dsh-plugin/） ▼ ComfyUI HTTP API (127.0.0.1:8188)

桥接插件只读复用 server，不修改也不复刻它的实现，更不会碰另外三个智能体的注册。

仓库结构

comfyui-agent-kit/
├─ mcp-server/
│ ├─ server.py # stdio JSON-RPC，8 个基础工具（仅用 Python 标准库） │ ├─ features.py # 11 个扩展工具（工作流/节点/项目资产/SDXL LoRA 训练） │ └─ comfyui_recipes.py # 可选：两段式出图配方（hires-fix / 面部特写） ├─ dsh-plugin/ │ ├─ package.json # dsh.bundle.patch 指向下面的补丁 │ ├─ cordis.patch.yml # 只插入自己一行，不替换任何官方组件 │ └─ lib/index.js # 桥接实现 └─ examples/ └─ sdxl-lora-txt2img.json

环境要求

| 依赖 | 说明 |
| ComfyUI | 需已启动，默认 http://127.0.0.1:8188（HTTP API） |
| Python | 3.8+，只用标准库，无需 pip 安装任何包 |
| Node.js | ≥ 22（仅 DSH 插件需要） |
| kohya_ss | 可选，仅 comfyui_lora_ 训练工具需要 |

安装

1. 放置 MCP server

把 mcp-server/ 两个文件放到任意固定目录。默认查找位置：

~/.agents/mcp-servers/comfyui/server.py

（Windows 即 C:\Users\<你>\.agents\mcp-servers\comfyui\server.py。）

2. 各智能体注册

Codex — ~/.codex/config.toml：

[mcp_servers.comfyui-local]
command = "py" # Windows；其他平台用 python3
args = ["-3", "C:\\Users\\<你>\\.agents\\mcp-servers\\comfyui\\server.py"]
startup_timeout_sec = 10

[mcp_servers.comfyui-local.env]
COMFYUI_URL = "http://127.0.0.1:8188"
COMFYUI_HOME = "E:\\Program\\ComfyUI"
COMFYUI_PROJECT_ROOT = "D:\\comfyui-project"
KOHYA_SS_ROOT = "E:\\Program\\kohya_ss"

Claude Code — ~/.claude.json：

{
"mcpServers": {
"comfyui-local": {
"type": "stdio",
"command": "C:\\Windows\\py.exe",
"args": ["-3", "C:\\Users\\<你>\\.agents\\mcp-servers\\comfyui\\server.py"],
"env": {
"COMFYUI_URL": "http://127.0.0.1:8188",
"COMFYUI_HOME": "E:\\Program\\ComfyUI",
"COMFYUI_PROJECT_ROOT": "D:\\comfyui-project",
"KOHYA_SS_ROOT": "E:\\Program\\kohya_ss"
}
}
}
}

ZCode — ~/.zcode/cli/config.json：

{
"mcp": {
"servers": {
"comfyui-local": {
"command": "C:\\Windows\\py.exe",
"args": ["-3", "C:\\Users\\<你>\\.agents\\mcp-servers\\comfyui\\server.py"],
"env": {json
"COMFYUI_URL": "http://127.0.0.1:8188",
"COMFYUI_HOME": "E:\\Program\\ComfyUI",
"COMFYUI_PROJECT_ROOT": "D:\\comfyui-project",
"KOHYA_SS_ROOT": "E:\\Program\\kohya_ss"
}
}
}
}
}

DSH —— 安装本地包并挂进配置档： powershell
dsh plugin --profile desktop add "C:\path\to\comfyui-agent-kit\dsh-plugin"

然后在该配置档的 package.json 里把 dsh-comfyui-mcp 加进 dsh.profile.bundles，重启桌面端： json {
"dsh": {
"profile": {
"bundles": [
"@deepseek-ai/dsh-web-app",
"dsh-comfyui-mcp"
]
}
}
}

装好后 comfyui_ 会直接出现在 DSH 的工具列表里，不需要再手写 subprocess 桥接。

环境变量

| 变量 | 默认值 | 用途 |
| COMFYUI_URL | http://127.0.0.1:8188 | ComfyUI HTTP 地址 |
| COMFYUI_TIMEOUT | 30 | 单次 HTTP 超时（秒） |
| COMFYUI_HOME | E:\Program\ComfyUI | ComfyUI 安装目录（定位 workflows / models） |
| COMFYUI_PROJECT_ROOT | ~/comfyui-project | 目标项目根（LoRA 数据集与 assets/art） |
| KOHYA_SS_ROOT | E:\Program\kohya_ss | kohya_ss 安装目录 |
| COMFYUI_MCP_PYTHON | C:\Windows\py.exe（Windows）/ python3 | DSH 插件用来拉起 server 的解释器 |
| COMFYUI_MCP_SERVER | ~/.agents/mcp-servers/comfyui/server.py | server 脚本路径 |

后三个只影响 DSH 插件；其余对所有智能体生效。

工具（19 个）

| 组 | 工具 |
| ComfyUI 基础 | comfyui_status · comfyui_list_models · comfyui_queue_workflow · comfyui_queue_status · comfyui_get_history · comfyui_interrupt · comfyui_upload_image · comfyui_download_output |
| 节点与工作流 | comfyui_search_nodes · comfyui_get_node_schema · comfyui_build_workflow · comfyui_validate_workflow · comfyui_save_workflow |
| 出图配方 | comfyui_gen_hires（两段式：生成 → 放大 → 低 denoise 重绘；或方形面部模式） |
| 项目资产 | comfyui_apply_art |
| SDXL LoRA 训练 | comfyui_lora_preflight · comfyui_lora_prepare · comfyui_lora_start · comfyui_lora_status |

示例

examples/sdxl-lora-txt2img.json 是一个最小 SDXL 文生图 API workflow （Checkpoint → LoRA → 双 CLIP → KSampler → VAEDecode → SaveImage）： jsonc // 直接提交：comfyui_queue_workflow({"workflow_json": "<文件内容>"}) // 校验： comfyui_validate_workflow({"workflow_json": "<文件内容>"})

把 lora_name 换成你自己的 LoRA 相对路径即可，子目录要带上，例如 my_lora\my_lora.safetensors。

安全与隐私

- server 只连 COMFYUI_URL，不访问任何外网、无遥测。
- 默认只监听回环地址；如需暴露到局域网请自行加鉴权。
- comfyui_apply_art 覆盖已存在文件时要求显式 overwrite=true，并保留 *.before-comfyui.png 备份。
- 仓库内不含任何 API key / token。

License

MIT