ComfyUI MCP

English · Español

ComfyUI MCP — 通过 Model Context Protocol（MCP）为 AI Agent 生成图像

将 SDXL 图像生成接入网络中的任意 AI Agent。 开源 MCP 服务，通过 Model Context Protocol 将 ComfyUI（SDXL / RTX 3060）的推理能力提供给 Claude Code、Cursor、Windsurf、Hermes Gateway 及任何兼容客户端。FastMCP HTTP/SSE + GPU Arbiter，客户端零依赖，100% 使用你的硬件。

标签： mcp-server · comfyui · sdxl · image-generation · ai-agents · fastmcp · claude-code · cursor · hermes-gateway · gpu-arbiter · local-first · self-hosted

_{Agent 使用预设请求生成图像，并收到下载 URL——GPU 在服务端运行，客户端无需安装 PyTorch。}

---

💡 项目缘起

在多 Agent 环境中生成图像，需要在每台客户端机器上安装庞大的 PyTorch 库、配备专用 GPU 并进行复杂配置。ComfyUI MCP 通过充当解耦的 HTTP/SSE 中间件适配器解决了这一问题：

• 🚀 无需本地安装：任何客户端或网关都可通过端口 8201 上的 HTTP/SSE 使用图像生成功能，无需安装 PyTorch，也无需在本地下载 SDXL 模型。
• 🧠 智能 GPU 仲裁器：在 12GB GPU（RTX 3060）上自动切换 llama-server（LLMs）和 ComfyUI，避免 VRAM 冲突。
• 🎯 专业预设：通过 producto（RealVisXL V4.0）或 realista（Juggernaut XL）等预设，生成可用于生产的图像。

---

🏗️ 架构与组件边界

⚠️ 重要：了解系统边界

comfyui-mcp 仅负责 MCP 传输与接口层。它不包含 ComfyUI 推理引擎，也不包含模型权重文件。 有关 Linux/Pop!_OS 主机上后端服务的部署指南，请参阅 docs/SERVER_SETUP.md 和 docs/ARCHITECTURE.md。

 +-------------------------------------------------------+
 |                 Clientes MCP (LAN)                    |
 | (Claude Code CLI / Cursor / Windsurf / Hermes Gateway)|
 +-------------------------------------------------------+
                             |
                             | HTTP / SSE (Puerto 8201)
                             v
 +-------------------------------------------------------+
 |                  comfyui-mcp Server                   |
 |           (FastMCP + Workflow JSON Builder)           |
 +-------------------------------------------------------+
                             |
                             | Loopback HTTP (Puerto 8188)
                             v
 +-------------------------------------------------------+
 |                 ComfyUI Backend Host                  |
 |  (PyTorch + CUDA + SDXL Checkpoints + GPU Arbiter)    |
 +-------------------------------------------------------+

---

📦 快速安装

要求

• Python 3.11+
• uv ≥ 0.13.4（推荐）或 pip ≥ 26.2.2：更早版本仍信任已泄露的 emSign CA（GHSA-6q48-6c7w-9gw2）。pyproject.toml 要求 uv 达到最低版本（[tool.uv] required-version）。

克隆并安装

git clone https://github.com/GermaniU/comfyui-mcp.git
cd comfyui-mcp

# Crear entorno virtual e instalar
uv venv
source .venv/bin/activate
uv pip install -e .

---

⚙️ 配置（环境变量）

创建 .env 文件或导出以下变量：

变量	默认值	描述
COMFYUI_URL	http://127.0.0.1:8188	ComfyUI 引擎监听的 loopback URL。
COMFYUI_PUBLIC_URL	http://<YOUR_SERVER_IP>:8188	用于下载图像的公开/LAN 基础 URL。
MCP_HOST	0.0.0.0	MCP 服务的主机绑定地址。
MCP_PORT	8201	MCP 服务的 HTTP/SSE 端口。
MCP_AUTH_TOKEN	(空 = 无认证)	如果已设置，则每个 HTTP/SSE 请求都必须包含 Authorization: Bearer <token> 标头。
MCP_CORS_ORIGINS	*	允许的 CORS 来源，以逗号分隔。仅影响在浏览器中运行的客户端。

**安全性：**如果未设置 MCP_AUTH_TOKEN，局域网中的任何设备——或在局域网浏览器中打开的网页（CORS 为 *）——都可以生成图像并占用 GPU。除非网络完全可信，否则建议设置令牌。

---

🛠️ 暴露的工具（工具参考）

1. generate_image（txt2img）

使用 SDXL 根据文本提示词生成图像。

• 参数：
  • prompt（string，必填）：图像描述（使用英语效果更好）。
  • preset（string，可选）：producto、realista、rapido 或 anime。默认值："producto"。
  • aspect（string，可选）：1:1、4:5、5:4、9:16、16:9、3:2、2:3（约 1MP）。默认值："1:1"。
  • negative_prompt（string，可选）：要排除的元素。默认使用通用质量负面提示词。
  • seed（integer，可选）：用于保证可复现性的种子。默认随机。
  • batch（integer，可选）：每次调用生成的图像数（1-4）。默认值：1。
  • checkpoint、lora、lora_strength、steps、cfg（可选）：覆盖预设值。
  • filename_prefix（string，可选）：输出文件前缀。默认值："mcp"。
  • detail_face（bool，可选）：FaceDetailer 处理步骤（需要 Impact Pack）。默认值：false。
  • preview（bool，可选）：另外返回 JPEG 缩略图（约 512px），供模型查看结果。仅适用于支持视觉的客户端。默认值：false。

2. img2img（图生图）

通过设置去噪强度，对已生成的图像（位于 ComfyUI 的 output/ 中）进行变化。

• 参数：
  • image_filename（string，必填）：已生成文件的名称（例如：mcp_00001_.png）。
  • prompt（string，可选）：转换指令。留空 = 纯视觉变化。
  • denoise（float，可选）：0.0 表示完全相同，1.0 表示完全重新生成。默认值：0.55。
  • preset（string，可选）：默认值："realista"。
  • negative_prompt、seed、checkpoint、lora、lora_strength、steps、cfg、filename_prefix、preview（可选）。

3. generate_video（Wan 2.2）

使用 Wan 2.2 TI2V 5B 生成短片 MP4（24fps）。不提供图像时为 txt2video；提供 image_filename 时，会将该图像设为首帧并为其添加动画效果。需要视频模型（参见 SERVER_SETUP）。在 RTX 3060 上，每个片段需要耗时数分钟。

• 参数：
  • prompt（string，必填）：场景和运动描述（包括镜头和主体的运动），使用英语。
  • aspect（string，可选）：16:9（1280x704）、9:16（704x1280）或 1:1（960x960）。默认值："16:9"。
  • seconds（integer，可选）：时长，1-5。默认值：3。
  • image_filename（string，可选）：要为其添加动画效果的已生成图像（例如：mcp_00001_.png）；建议图像的 aspect 与视频一致。
  • draft（bool，可选）：以约 480p（832x480、480x832、640x640）生成草稿，像素数不到一半，速度快得多；可用于在生成最终版本前测试提示词。默认值：false。
  • negative_prompt、seed、steps、cfg、filename_prefix（可选）。前缀默认值："mcp-video"。
  • preview（bool，可选）：返回首帧的 JPEG 缩略图。默认值：false。

4. list_models

返回 ComfyUI 实例中可用的 checkpoint、LoRA 和预设列表。

5. comfy_health

获取后端的健康状态：ComfyUI 版本、GPU 的 VRAM 使用情况和队列中的任务。

6. comfy_view_url

根据之前生成的文件的 filename 和 subfolder，构建其 LAN 直接下载 URL。

---

🎨 预设矩阵

预设	关联的 Checkpoint	步数	CFG	用例
producto	RealVisXL_V4.0.safetensors	30	5.5	写实商业与产品摄影（默认）。
realista	juggernautXL_ragnarokBy.safetensors	30	5.0	多用途写实图像（场景、人物、环境）。
rapido	juggernautXL_ragnarokBy.safetensors + LoRA SDXL-Lightning	6	1.5	约 5 秒生成预览和草稿。
anime	animagine-xl-3.1.safetensors	28	7.0	动漫风格插画（服务端未包含该 checkpoint）。

---

🧭 ComfyUI 的其他 MCP 服务又有哪些？

它们分为三个类别，分别解决不同的问题。本项目不会与另外两类竞争，而是与它们互补。

	ComfyUI MCP（本项目）	workflow graph 服务	云端图像 API
你提供什么	一个提示词 + 预设（producto、realista、rapido、anime）	一个 JSON 格式的节点图（由你设计）	向远程服务提供提示词
是否需要了解 ComfyUI	不需要	需要	不需要
运行位置	你的 GPU（RTX 3060）	你的 GPU	第三方服务端
每张图像的成本	0（你的电费）	0	按图像计费，具体取决于提供商
隐私	提示词不会离开你的网络	同上	你的提示词会发送到云端
是否与大模型共用 GPU	是（GPU Arbiter，12 GB）	视情况而定	不适用
客户端	LAN 上的 HTTP/SSE + stdio — 客户端无需安装 PyTorch	通常为本地 stdio	HTTP

一句话概括：

• 如果你需要完全控制节点图 → 使用 workflow graph 服务（例如 comfy-pilot）。
• 如果你没有 GPU，也不介意按图像付费 → 使用云端 API（Flux、Nano Banana、GPT-image）。
• 如果你有 GPU，想要无需学习 ComfyUI 即可生成图像，并与大模型共用显卡 → 使用本项目。

---

🔗 与 MCP 客户端集成

Claude Code CLI 配置（~/.claude.json）

{
  "mcpServers": {
    "comfyui": {
      "url": "http://<YOUR_SERVER_IP>:8201/mcp"
    }
  }
}

Hermes Gateway 配置（~/.hermes/config.yaml）

mcp_servers:
  comfyui:
    url: "http://<YOUR_SERVER_IP>:8201/mcp"
    transport: "http"

Cursor / Windsurf / Claude Desktop 配置

添加一个类型为 SSE / HTTP 的 MCP 服务，URL 为 http://<LAN_IP>:8201/mcp。

---

📋 缺失组件与路线图（服务端缺口）

由于本仓库代表的是 MCP 层，以下内容不在本仓库中，需要在主机服务端进行配置：

1. ComfyUI 后端服务：需要单独安装 Python + PyTorch CUDA。
2. Checkpoint 下载：SDXL 模型必须手动下载到 ComfyUI 服务端的 models/checkpoints/ 目录中。
3. GPU Arbiter 脚本：脚本 gpu-broker.sh 和规则 /etc/sudoers.d/gpu-arbiter 必须放在配备 GPU 的 Linux 机器上。
4. MCP 的未来改进：
   • 支持动态注入自定义 JSON 工作流。
   • 支持通过 MCP 工具取消和清理处理队列。
   • 通过 WebSocket 连接实时报告进度。

---

🧪 单元测试

uv run --with pytest --with pytest-asyncio pytest

---

📄 许可证

本项目采用 MIT 许可证。更多详情请参阅 LICENSE 文件。