comfyui-mcp

通过 MCP (Model Context Protocol) 协议调用 ComfyUI，加载并执行 workflow：文生图、图编辑、放大、去背景等。适用于 opencode、Claude Code、Cursor 等 MCP 客户端。

---

快速启动

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 文件，重启后自动注册。目录不存在时自动创建。

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

需要多个目录时：

--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 实例、跨机部署等场景。

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

{
  "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：

{
  "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 中。

---

本地开发

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

或安装为本地命令：

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

---

License

MIT — 详见 LICENSE。