comfyui-mcp

ComfyUI 的 MCP 服务器。使用任何兼容 MCP 的客户端，通过自然语言提示词生成图像。

属于 MCP 服务器系列。

状态

v0.2 — 核心工具，外加放大、图像代理和公共 URL 支持。工具：generate_image、generate_variations、generate_with_workflow、refine_image、upscale_image、list_models、list_workflows、upload_image。查看路线图了解后续计划。

安装

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

或者将流式 HTTP 端点注册到 MCP 网关（例如 MetaMCP）以与其他服务器聚合。

配置

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

返回给客户端的图像 URL

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

服务器还提供了一个代理端点：GET /images/<filename>?subfolder=&type=output，通过 MCP 服务器流式传输图像字节 — 当客户端可以访问 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）。

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 客户端之间移植。

模板名称必须以字母数字开头；支持 a-z, A-Z, 0-9, -, _；最大 64 个字符。

返回格式

所有生成工具返回的图像 URL 均由 ComfyUI 实例直接提供 (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+。

路线图

• [x] generate_image — 使用默认工作流进行文生图

• [x] generate_with_workflow — 提交任意工作流

• [x] list_models / list_workflows

• [x] upload_image — 用于 img2img / ControlNet / IP-Adapter 的参考图像

• [x] generate_variations — 提示词的批量变体

• [x] refine_image — 从源 URL 进行 img2img 优化

• [x] upscale_image — ESRGAN/SwinIR 风格的模型放大

• [x] 图像代理端点 (/images/<filename>)，适用于无法访问 ComfyUI 的客户端

• [x] 可配置的公共 URL，用于获取外部正确的图像 URL

• [x] 工作流模板注册表：save_workflow_template, list_workflow_templates, get_workflow_template, delete_workflow_template, run_workflow_template

• [x] ControlNet 工作流助手：generate_with_controlnet (需要 ComfyUI 端的 ControlNet 模型)

• [x] IP-Adapter 工作流助手：generate_with_ip_adapter (需要 ComfyUI-IPAdapter-plus 包)

• [ ] 用于长时间生成任务的 WebSocket 进度事件

许可证

MIT © Joe Miller

支持

如果此工具为您节省了时间，请考虑支持开发：

每一笔贡献都将资助 MCP 服务器系列 的维护、文档编写和后续版本发布。