comfyui-mcp

comfyui-mcp

适用于 ComfyUI 的 MCP 服务。在任何兼容 MCP 的客户端中，使用自然语言提示词生成图像。

状态

v0.2 发布了核心工具，以及放大、图像代理和公共 URL 支持。当前提供的工具：generate_image、generate_variations、generate_with_workflow、refine_image、upscale_image、list_models、list_workflows、upload_image、generate_with_controlnet、generate_with_ip_adapter，以及工作流模板注册表。后续计划请参阅 Roadmap。

安装

npx（无需安装）

npx @miller-joe/comfyui-mcp --comfyui-url http://your-comfyui-host:8188

npm

npm install -g @miller-joe/comfyui-mcp
comfyui-mcp --comfyui-url http://your-comfyui-host:8188

Docker

docker run -p 9100:9100 \
  -e COMFYUI_URL=http://your-comfyui-host:8188 \
  ghcr.io/miller-joe/comfyui-mcp:latest

连接 MCP 客户端

Claude Code：

claude mcp add --transport http comfyui http://localhost:9100/mcp

或者向 MCP 网关（例如 MetaMCP）注册可流式传输的 HTTP 端点，以便与其他服务聚合。

配置

所有选项均可通过 CLI 标志或环境变量设置：

CLI 标志	环境变量	默认值	描述
--host	MCP_HOST	0.0.0.0	绑定主机（仅限 HTTP 模式）
--port	MCP_PORT	9100	绑定端口（仅限 HTTP 模式）
--stdio	MCP_TRANSPORT=stdio	（未设置）	使用 stdio 而不是 HTTP 进行 MCP 通信。由优先使用 stdio 的 MCP 客户端（Claude Desktop、mcp-inspector）作为子进程启动时使用。
--comfyui-url	COMFYUI_URL	http://127.0.0.1:8188	此服务内部使用的 ComfyUI HTTP URL
--comfyui-public-url	COMFYUI_PUBLIC_URL	与 --comfyui-url 相同	返回给客户端的图像 URL 中使用的外部 URL。当 MCP 客户端无法访问内部 URL 时（Docker 网络中很常见），请设置此项。
（无标志）	COMFYUI_DEFAULT_CKPT	sd_xl_base_1.0.safetensors	默认检查点文件名

传输方式

服务默认使用可流式传输的 HTTP（非常适合 Claude Code、MetaMCP 和原始 fetch）。传入 --stdio（或设置 MCP_TRANSPORT=stdio）即可切换到 stdio 模式，这是 Claude Desktop 和 MCP Inspector 等优先使用 stdio 的客户端所需的模式：

# Claude Desktop config (claude_desktop_config.json):
{
  "mcpServers": {
    "comfyui": {
      "command": "npx",
      "args": ["-y", "@miller-joe/comfyui-mcp", "--stdio", "--comfyui-url", "http://127.0.0.1:8188"]
    }
  }
}

返回给客户端的图像 URL

图像生成工具会返回类似 <comfyui-public-url>/view?filename=… 的图像 URL。如果未设置 --comfyui-public-url，URL 将使用内部的 --comfyui-url 值。

服务还提供了一个代理端点：GET /images/<filename>?subfolder=&type=output 会通过此服务传输图像字节，这适用于客户端能够访问 MCP 服务、但无法直接访问 ComfyUI 的情况。

默认检查点必须与 ComfyUI models/checkpoints/ 目录中的文件匹配。可通过 COMFYUI_DEFAULT_CKPT 覆盖，或将 checkpoint 作为工具参数传入。

工具

generate_image

使用 ComfyUI 的默认 txt2img 工作流，根据文本提示词生成图像。

参数：prompt（必需）、negative_prompt、width、height、steps、cfg、seed、checkpoint。

generate_variations

通过改变种子，为同一提示词生成多个变体。一次性返回所有图像。

参数：prompt（必需）、count（2–16，默认值为 4），以及与 generate_image 相同的生成参数，但使用 base_seed 代替 seed。

generate_with_workflow

提交任意 ComfyUI 工作流 JSON（完整节点图），并返回生成的图像 URL。用于自定义工作流，例如 ControlNet、放大，或从 ComfyUI 的 Save (API Format) 导出的任何工作流。

参数：workflow（对象），完整节点图。

refine_image

对源图像运行 img2img。服务会获取源 URL，将其上传到 ComfyUI，并根据新提示词运行一次去噪处理。denoise 值越低，保留的原图内容越多；值越高，提示词发挥的空间越大。

参数：prompt、source_image_url（必填）、denoise（0–1，默认值为 0.5），以及标准生成参数。

list_models

列出 ComfyUI 实例上可用的检查点、LoRA、采样器或调度器。

参数：kind，可选 checkpoints（默认值）、loras、samplers、schedulers。

list_workflows

列出此服务自带的工作流模板（目前包括 txt2img、img2img、upscale、controlnet、ip_adapter）。

upload_image

将参考图像上传到 ComfyUI，以用于 img2img、ControlNet 或 IP-Adapter 工作流。

参数：source_url 或 image_base64（必填其一）、filename（可选）、overwrite（默认值为 false）。

返回：存储的文件名，可用作 LoadImage 等工作流节点的 image 输入。

generate_with_controlnet

使用经过 ControlNet 预处理的图像（姿势骨架、深度图、Canny 边缘、法线贴图等）和文本提示词进行条件图像生成。

参数：prompt、control_image_url（预处理后的条件图像；此工具不会运行预处理器）、controlnet_model（来自 models/controlnet/ 的文件名）、strength（0–2，默认值为 1）、start_percent / end_percent（0–1，用于控制 CN 在采样过程中何时生效），以及标准生成参数。

需要在 ComfyUI 的 models/controlnet/ 目录中安装 ControlNet 模型。

generate_with_ip_adapter

通过 IP-Adapter 使用参考图像作为视觉、风格或主体指引来生成图像。

参数：prompt、reference_image_url、preset（例如 "STANDARD (medium strength)"、"PLUS FACE (portraits)"、"VIT-G (medium strength)"）、weight（0–3，默认值为 1）、start_at / end_at（0–1），以及标准生成参数。

需要安装 ComfyUI-IPAdapter-plus 自定义节点包，以及与预设匹配的 IPAdapter 权重和 CLIP Vision 模型。

工作流模板注册表

保存复杂工作流 JSON，之后可按名称运行。模板存储在 --templates-dir 指定的磁盘目录下（默认路径为 ~/.config/comfyui-mcp/templates/<name>.json），因此重启后仍会保留，并可在不同 MCP 客户端之间移植。

工具	描述
save_workflow_template	将工作流 JSON 保存到指定名称的槽位。设置 overwrite=true 可替换已有模板。
list_workflow_templates	列出已保存的模板，包括描述和上次更新时间戳。
get_workflow_template	获取已存储模板的 JSON 和元数据。
delete_workflow_template	删除已存储的模板。
run_workflow_template	对 ComfyUI 运行已保存的模板，并返回图像 URL。

模板名称必须以字母或数字开头。允许使用：a-z、A-Z、0-9、-、_。最多 64 个字符。

返回格式

所有生成工具都会返回由 ComfyUI 实例直接提供的图像 URL（http://<comfyui>/view?filename=…）。这些 URL 可直接传给任何接受图像 URL 的客户端。

架构

┌────────────────┐     ┌──────────────────┐     ┌──────────────┐
│  MCP client    │────▶│  comfyui-mcp     │────▶│  ComfyUI     │
│  (Claude, etc.)│◀────│  (this server)   │◀────│  instance    │
└────────────────┘     └──────────────────┘     └──────────────┘
     streamable HTTP        HTTP REST + poll

此服务无状态。单个 MCP 请求会向 ComfyUI 提交工作流，轮询 /history/{id} 直至完成，然后返回图像 URL。

开发

git clone https://github.com/miller-joe/comfyui-mcp
cd comfyui-mcp
npm install
npm run dev       # hot-reload via tsx watch
npm run build     # compile TS to dist/
npm run typecheck # strict type checking

需要 Node 20+。

路线图

已在 v0.2 中发布：

• generate_image、generate_variations、generate_with_workflow
• refine_image（从源 URL 进行 img2img）
• upscale_image（ESRGAN / SwinIR 风格的模型放大）
• list_models、list_workflows、upload_image
• 图像代理端点（/images/<filename>），供无法直接访问 ComfyUI 的客户端使用
• 可配置的公共 URL，确保图像 URL 对外部访问有效
• 工作流模板注册表（保存 / 列出 / 获取 / 删除 / 运行）
• generate_with_controlnet（需要 ComfyUI 端安装 ControlNet 模型）
• generate_with_ip_adapter（需要 ComfyUI-IPAdapter-plus 扩展包）

计划中：

• 为长时间运行的生成任务提供 WebSocket 进度事件。

许可证

MIT © Joe Miller

支持

如果此工具为你节省了时间，可以考虑支持开发工作：

每笔捐助都将用于维护、文档编写和下一次发布。