comfyui-mcp

MCP Server that connects local ComfyUI to AI Agents (e.g. Trae). Control ComfyUI entirely via natural language — create workflows, configure models, generate images, manage the queue — without touching the ComfyUI UI.

功能

• 20 个 MCP 工具：模型列表、节点类型、工作流构建/执行、图片上传下载、队列管理、原子节点操作
• 7 个 MCP Resources：checkpoints、loras、vaes、upscalers、controlnet、节点类型定义、系统信息
• 模板驱动 + 动态构建：内置 txt2img / img2img 模板，也支持自定义工作流
• 中间表示层：用简洁的 IR dict 描述工作流，由 MCP Server 翻译为 ComfyUI 原生 JSON
• 统一错误格式：所有工具返回 {success: true/false, error: "...", error_code: "..."}
• 自动检测 ComfyUI：启动时检测可用性，不可达不阻塞

环境要求

• Python 3.10+
• ComfyUI 本地运行（默认 http://127.0.0.1:8188）

安装依赖

pip install -r requirements.txt

部署到 Trae

1. 打开 Trae → 设置 → MCP → 添加 MCP Servers
2. 选择手动配置，粘贴以下 JSON（将路径改为你的实际路径）：

{
  "mcpServers": {
    "comfyui": {
      "command": "python",
      "args": ["C:\\path\\to\\comfyui_mcp_project\\src\\server.py"]
    }
  }
}

3. 保存。Trae 会自动启动 MCP Server，Agent 即可调用工具。

直接运行

cd comfyui_mcp_project
python src/server.py

环境变量（可选）

变量	默认值	说明
COMFYUI_BASE_URL	http://127.0.0.1:8188	ComfyUI 地址
LOG_LEVEL	INFO	日志级别（DEBUG/INFO/WARNING/ERROR）
LOG_DIR	logs/	日志文件目录
LOG_MAX_DAYS	7	日志保留天数
THUMBNAIL_MAX_SIZE	512	缩略图最大边长（px）

核心工具速查

工具	说明
list_models	列出可用模型（checkpoints/loras/vaes/upscalers/controlnet）
get_node_types	获取所有节点类型定义
load_template	加载内置或用户模板
build_workflow	从 IR dict 构建工作流并设为当前工作流
execute_workflow	提交当前工作流到 ComfyUI 执行
get_execution_status	查询执行状态
get_generated_image	下载生成的图片（含缩略图 base64 + 原图路径）
create_node / update_node / remove_node	原子操作：增/改/删工作流节点
connect_nodes / disconnect_nodes	原子操作：连接/断开节点

中间表示（IR）示例

{
    "type": "txt2img",
    "checkpoint": "sdXL_v10VAEFix.safetensors",
    "positive_prompt": "cyberpunk city at night, neon lights",
    "negative_prompt": "blurry, cartoon",
    "width": 1024,
    "height": 1024,
    "steps": 25,
    "cfg": 7.0,
    "seed": -1,
}

项目结构

comfyui_mcp_project/
├── src/
│   ├── server.py              # MCP Server 入口
│   ├── comfyui_client.py      # ComfyUI REST API 客户端
│   ├── workflow_builder.py     # IR → ComfyUI JSON 翻译
│   ├── context.py             # 共享上下文
│   ├── templates/             # 内置模板
│   │   ├── txt2img.json
│   │   └── img2img.json
│   └── tools/                 # MCP 工具实现
├── design_doc/                # 设计文档
├── user_templates/            # 用户自定义模板
├── requirements.txt
└── pyproject.toml

详细设计文档见 design_doc/。