ComfyUI MCP 服务器
这是一个 Model Context Protocol (MCP) 服务器，用于动态加载和执行 ComfyUI 工作流。它会自动扫描指定文件夹中的工作流，并将每个工作流作为独立的工具暴露给大模型。
功能特点
- 动态加载 ComfyUI 工作流文件夹
- 基于描述文件的参数映射系统
- 通过 WebSocket 监听工作流执行进度
- 支持 WSL2 环境（自动绕过代理）
- 灵活的参数配置和默认值
- 支持自定义输出目录
快速开始
1. 安装和构建
# 克隆或进入项目目录
cd comfyui-mcp
# 安装依赖
npm install
# 构建项目
npm run build
# 记录当前目录的绝对路径（后续配置需要）
pwd # 例如：/home/username/comfyui-mcp
2. 配置环境
WSL2 用户：检测 Windows 主机 IP
bash scripts/detect-wsl2-host.sh
创建配置文件
cp .env.example .env
编辑 .env 文件：
# ComfyUI 工作流文件夹路径
WORKFLOWS_DIR=./workflows
# ComfyUI 服务器配置
COMFYUI_HOST=172.22.240.1 # WSL2 中的 Windows 主机 IP
COMFYUI_PORT=8000
# 绕过系统代理（WSL2 环境建议开启）
BYPASS_PROXY=true
3. 测试连接
node test-connection.js
4. 在 Claude Desktop 中配置
编辑 Claude Desktop 配置文件：
- Windows:
%APPDATA%\Claude\claude_desktop_config.json - macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Linux:
~/.config/Claude/claude_desktop_config.json
添加 MCP 服务器配置（使用绝对路径）：
{
"mcpServers": {
"comfyui": {
"command": "npx",
"args": ["/absolute/path/to/comfyui-mcp"],
"env": {
"WORKFLOWS_DIR": "/absolute/path/to/comfyui-mcp/workflows",
"COMFYUI_HOST": "172.22.240.1",
"COMFYUI_PORT": "8000",
"BYPASS_PROXY": "true"
}
}
}
}
示例配置（WSL2）：
{
"mcpServers": {
"comfyui": {
"command": "npx",
"args": ["/home/yarnb/xcan/comfyui-mcp"],
"env": {
"WORKFLOWS_DIR": "/home/yarnb/xcan/comfyui-mcp/workflows",
"COMFYUI_HOST": "172.22.240.1",
"COMFYUI_PORT": "8000",
"BYPASS_PROXY": "true"
}
}
}
}
注意事项：
WORKFLOWS_DIR必须是绝对路径COMFYUI_HOST使用检测脚本获取的 IP- 配置后需要重启 Claude Desktop
5. 验证安装
重启 Claude Desktop 后，在对话中输入：
使用 Qwen 模型生成一张中国山水画
Claude 会自动识别并调用对应的工具。
6. 使用自定义输出目录
所有工具都支持指定输出目录参数：
使用 run_text_to_image_workflow_flux_schnell 工具生成图片，
prompt: "beautiful sunset",
output_dir: "/home/username/my_images"
如果不指定 output_dir，文件将保存到默认的 outputs 目录。
工作流组织结构
工作流按照功能分类组织，每个工作流都在独立的文件夹中：
workflows/
├── text-to-image/ # 文本生成图像
│ └── image_qwen_image/ # Qwen 视觉语言模型
├── image-to-image/ # 图像转图像/编辑
│ ├── omnigen2_image_edit/ # OmniGen2 智能编辑
│ ├── qwen_image_edit/ # Qwen 图像编辑
│ ├── qwen_image_controlnet_patch/ # Qwen + ControlNet Patch
│ ├── qwen_image_instantx_controlnet/ # Qwen + InstantX ControlNet
│ ├── qwen_image_union_control/ # Qwen + Union Control
│ ├── rmbg_multiple_models/ # 多模型背景移除
│ └── yolo_cropper/ # YOLO 智能裁剪
├── image-to-video/ # 图像生成视频
│ ├── wan2_2_14b_i2v/ # WAN 2.2 14B 图生视频
│ └── wan2_2_14b_flf2v/ # WAN 2.2 14B 首尾帧插值
├── text-to-video/ # 文本生成视频
│ └── wan2_2_14b_t2v/ # WAN 2.2 14B 文生视频
├── text-to-audio/ # 文本生成音频
│ ├── audio_ace_step_1_t2a_instrumentals/ # ACE 纯器乐生成
│ └── audio_ace_step_1_t2a_song/ # ACE 带歌词音乐生成
└── audio-to-audio/ # 音频编辑
└── audio_ace_step_1_a2a_editing/ # ACE 音频编辑
每个工作流文件夹包含：
├── workflow.json # ComfyUI 导出的工作流 JSON（统一命名）
├── descriptor.json # 参数描述文件（包含分类信息）
└── README.md # 工作流详细说明（可选）
描述文件格式
descriptor.json 定义了工作流的参数及其在 JSON 中的路径：
{
"description": "工作流的描述",
"parameters": [
{
"name": "prompt", // 参数名称
"type": "string", // 参数类型（string/number/boolean）
"subtype": "image", // 子类型（可选，用于标识特殊参数如图片）
"description": "描述词", // 参数说明
"required": true, // 是否必需
"path": "6.inputs.text", // JSON 路径
"default": "默认值" // 默认值（可选）
}
]
}
参数路径说明
path 字段使用点号分隔的路径来定位 JSON 中的值：
"6.inputs.text"对应workflow[6].inputs.text"3.inputs.seed"对应workflow[3].inputs.seed
添加新工作流
步骤 1：导出 ComfyUI 工作流
- 在 ComfyUI 中创建或打开工作流
- 点击菜单 → Save (API Format)
- 保存 JSON 文件
步骤 2：创建工作流文件夹
根据工作流类型选择正确的分类目录：
text-to-image/- 文本生成图像image-to-image/- 图像编辑、转换、处理image-to-video/- 图像生成视频text-to-video/- 文本生成视频text-to-audio/- 文本生成音频/音乐audio-to-audio/- 音频编辑、风格转换
# 例如添加一个新的文生图工作流
mkdir workflows/text-to-image/my_workflow
# 复制工作流文件（必须命名为 workflow.json）
cp path/to/exported.json workflows/text-to-image/my_workflow/workflow.json
步骤 3：创建描述文件 (descriptor.json)
创建 workflows/[category]/my_workflow/descriptor.json：
{
"description": "详细的工具能力描述（参考下方编写指南）",
"category": "text-to-image",
"parameters": [
{
"name": "prompt",
"type": "string",
"description": "参数的详细说明，包含使用建议",
"required": true,
"path": "6.inputs.text",
"default": "默认值示例"
},
{
"name": "input_image",
"type": "string",
"subtype": "image", // 标记为图片参数，系统会自动处理上传
"description": "输入图片路径",
"required": true,
"path": "10.inputs.image",
"default": ""
}
]
}
📝 描述文件编写指南
1. 工具描述 (description) 编写要点
必须包含的信息：
- 核心功能：这个工具能做什么
- 技术特点：使用什么模型/技术，有何独特优势
- 应用场景：适合什么场景使用
- 关键参数：重要的参数说明（如分辨率、时长等）
- 特殊要求：如必须提供的输入
⚠️ 重要：参数默认值处理规则
- 必填参数（required: true）：
- 不应设置默认值，或设置为空字符串
"" - 用户必须明确提供输入值
- 例如：正面提示词、输入图片路径、音频描述等
- 不应设置默认值，或设置为空字符串
- 非必填参数（required: false）：
- 影响创作结果的参数（如负面提示词）应设为
null而非具体值 - 技术参数（如 steps、cfg、seed）可以有合理的默认值
- 避免预设内容影响用户的创作意图
- 影响创作结果的参数（如负面提示词）应设为
好的描述示例：
{
"description": "使用 FLUX.1 Schnell 极速版模型，仅需4步即可生成高质量图像，是速度最快的文生图模型。特别优化了生成速度，适合需要快速预览、实时交互或批量生成的场景。虽然步数少但质量依然出色，支持1024x1024及更高分辨率。是快速原型设计的首选。"
}
描述模板：
使用 [模型名称] [核心功能描述]。[技术特点说明]。[适用场景列举]。[关键能力或限制]。[特殊说明]。
2. 参数描述 (parameter description) 编写要点
必须说明的内容：
- 参数的作用
- 可接受的值或范围
- 对结果的影响
- 使用建议
参数描述示例：
{
"parameters": [
{
"name": "prompt",
"description": "描述想要生成的图像内容，支持中英文，越详细效果越好"
},
{
"name": "denoise",
"description": "去噪强度 (0-1)：0.1-0.3轻微修改，0.4-0.7中等变化，0.8-1.0大幅重绘"
},
{
"name": "duration",
"description": "音频时长（秒）：1-5秒短音效，10-30秒音乐片段，30-180秒完整作品"
},
{
"name": "input_image",
"type": "string",
"subtype": "image", // 重要：图片参数必须添加此标记
"description": "输入图片的绝对路径，支持 jpg/png 等常见格式"
}
]
}
特殊参数类型说明：
-
图片参数：必须添加
"subtype": "image"标记- 系统会自动检测并处理图片上传
- 支持本地文件路径（自动上传）或已上传的文件名
- 支持多个图片输入（如 start_image、end_image）
-
输出目录参数（自动添加到所有工具）：
- 参数名：
output_dir - 类型：string（可选）
- 功能：指定生成文件的保存位置
- 示例：
"/home/username/project/assets" - 默认：项目根目录下的
outputs文件夹
- 参数名：
3. 分类选择指南
| 分类 | 说明 | 工具名称格式 |
|---|---|---|
| text-to-image | 根据文本生成图像 | run_text_to_image_workflow_[name] |
| image-to-image | 修改或转换现有图像 | run_image_to_image_workflow_[name] |
| image-to-video | 静态图像转动态视频 | run_image_to_video_workflow_[name] |
| text-to-video | 根据文本生成视频 | run_text_to_video_workflow_[name] |
| text-to-audio | 根据文本生成音频/音乐 | run_text_to_audio_workflow_[name] |
| audio-to-audio | 编辑或转换现有音频 | run_audio_to_audio_workflow_[name] |
步骤 4：创建 README.md（可选但推荐）
为工作流创建详细文档 workflows/[category]/my_workflow/README.md：
# 工作流名称
## 概述
工作流的详细介绍
## 工作流特点
- 特点1
- 特点2
## 主要参数
详细的参数说明
## 使用示例
具体的使用案例
## 注意事项
使用时的注意点
步骤 5：查找参数路径
- 打开工作流 JSON 文件
- 找到需要暴露的参数节点
- 记录节点 ID 和输入字段名
- 组合成路径格式：
节点ID.inputs.字段名
例如，在 JSON 中找到：
{
"6": {
"inputs": {
"text": "提示词内容"
}
}
}
对应路径为：6.inputs.text
步骤 6：重启 Claude Desktop
添加新工作流后，需要重启 Claude Desktop 以重新加载工作流。
📚 描述编写最佳实践
让 AI 更好理解你的工具
✅ 好的工具描述
"description": "基于现有图像进行智能修改和风格转换的强大工具。可以将照片转换为不同艺术风格（油画、水彩、动漫等），修改图像内容（更换背景、改变季节、调整光线），或增强图像质量。通过调节去噪强度(denoise)精确控制修改程度，从轻微调整到完全重绘。必须提供输入图片路径。"
为什么好？
- 明确说明了工具的核心能力（修改、转换）
- 列举了具体功能（风格转换、内容修改、质量增强）
- 提供了关键参数说明（denoise）
- 强调了必需输入（图片路径）
❌ 差的工具描述
"description": "图生图工作流"
为什么差？
- 太简短，AI 不知道具体能做什么
- 没有说明使用场景
- 缺少技术特点
参数描述技巧
1. 对于数值参数，提供范围和效果说明
{
"name": "cfg",
"description": "CFG强度(1-20)：1-3创意自由，4-7平衡效果，8-20严格遵循提示"
}
2. 对于文件路径，说明格式要求
{
"name": "input_image",
"description": "输入图片的绝对路径，支持 jpg/png/webp 格式，建议分辨率不低于512x512"
}
3. 对于选择型参数，列出所有选项
{
"name": "style",
"description": "艺术风格：realistic(写实)、anime(动漫)、oil_painting(油画)、watercolor(水彩)"
}
4. 对于复杂参数，提供示例
{
"name": "prompt",
"description": "图像描述，示例：'阳光明媚的海滩，椰子树，蓝天白云，4K高清，专业摄影'"
}
常用描述词汇参考
技术特点词汇：
- 极速生成、高质量、专业级、优化版、增强版
- 智能识别、精确控制、自动优化、实时处理
- 支持批量、多格式兼容、高分辨率
应用场景词汇：
- 适合...场景、特别擅长...、专为...优化
- 创意设计、专业制作、快速原型、批量处理
- 个人创作、商业应用、教育演示
能力描述词汇：
- 可以...、支持...、能够...、实现...
- 生成、转换、修改、增强、优化、创建
- 自定义、调节、控制、设置
📖 相关文档
- Negative Prompt 使用规范 - 了解如何正确编写负向提示词
✔️ 添加工作流前的检查清单
在添加新工作流前，请确保：
- 工作流放在正确的分类文件夹中
- workflow.json 文件名正确
- descriptor.json 包含 category 字段
- 工具描述清晰说明了能力和使用场景
- 每个参数都有详细的描述
- 必需参数都标记为 required: true
- 提供了合理的默认值
- 参数路径 (path) 正确对应 JSON 节点
- （可选）创建了 README.md 详细文档
开发模式
本地开发
# 开发模式（自动重载）
npm run dev
# 重新构建
npm run build
直接运行
# 直接运行编译后的文件
node dist/index.js
# 或在 Claude 配置中使用
{
"command": "node",
"args": ["/absolute/path/to/comfyui-mcp/dist/index.js"]
}
故障排除
Claude Desktop 无法找到工具
- 确认项目路径正确（使用绝对路径）
- 检查 Claude 配置文件格式是否正确
- 查看 Claude 的开发者工具日志
WSL2 连接问题
如果无法连接到 Windows 上的 ComfyUI：
- 确保 ComfyUI 启动时使用
--listen 0.0.0.0参数 - 检查 Windows 防火墙是否允许端口访问
- 运行
scripts/detect-wsl2-host.sh重新检测 IP - 确保
BYPASS_PROXY=true已设置
工作流加载失败
检查以下几点：
- 工作流文件夹名称与内部 JSON 文件名一致
descriptor.json格式正确- JSON 路径与实际工作流结构匹配
- 查看控制台错误信息
npx 执行错误
如果 npx 无法执行：
# 确保使用绝对路径
npx /home/username/comfyui-mcp
# 或直接使用 node
node /home/username/comfyui-mcp/dist/index.js
工作原理
- 工作流加载：启动时扫描
workflows文件夹的分类目录，加载所有工作流 - 工具注册：每个工作流注册为
run_{category}_workflow_{name}格式的工具- 例如：
run_text_to_image_workflow_flux_schnell - 例如：
run_image_to_video_workflow_image_to_video_wan
- 例如：
- 参数处理：接收输入参数，根据描述文件的路径映射修改工作流 JSON
- 执行监控：通过 WebSocket 连接 ComfyUI，监听执行进度
- 结果返回：执行完成后返回生成结果
示例工作流
项目包含多个分类的专业工作流：
文本生成图像 (text-to-image)
run_text_to_image_workflow_image_qwen_image- Qwen 视觉语言模型，支持中英文提示词
图像编辑与处理 (image-to-image)
run_image_to_image_workflow_omnigen2_image_edit- OmniGen2 多模态图像编辑run_image_to_image_workflow_qwen_image_edit- Qwen 智能图像编辑run_image_to_image_workflow_qwen_image_controlnet_patch- Qwen + ControlNet 精确控制run_image_to_image_workflow_qwen_image_instantx_controlnet- Qwen + InstantX 深度控制run_image_to_image_workflow_qwen_image_union_control- Qwen + Union Control 边缘控制run_image_to_image_workflow_rmbg_multiple_models- 多模型背景移除run_image_to_image_workflow_yolo_cropper- YOLO 智能物体检测与裁剪
视频生成 (image-to-video & text-to-video)
run_image_to_video_workflow_wan2_2_14b_i2v- WAN 2.2 14B 图片转动态视频run_image_to_video_workflow_wan2_2_14b_flf2v- WAN 2.2 14B 首尾帧智能插值run_text_to_video_workflow_wan2_2_14b_t2v- WAN 2.2 14B 文本生成视频
音频与音乐生成 (text-to-audio & audio-to-audio)
run_text_to_audio_workflow_audio_ace_step_1_t2a_instrumentals- ACE 纯器乐音乐生成run_text_to_audio_workflow_audio_ace_step_1_t2a_song- ACE 带歌词歌曲生成run_audio_to_audio_workflow_audio_ace_step_1_a2a_editing- ACE 音频智能编辑
使用示例：
# 文本生成图像
run_text_to_image_workflow_image_qwen_image:
prompt: "山水画，中国传统风格，青山绿水"
width: 1024
height: 1024
output_dir: "/home/user/outputs"
output_name: "chinese_painting"
# 智能图像编辑
run_image_to_image_workflow_qwen_image_edit:
input_image: "/path/to/image.jpg"
positive_prompt: "去除图片中的文字水印"
output_dir: "/home/user/outputs"
output_name: "clean_image"
# 背景移除
run_image_to_image_workflow_rmbg_multiple_models:
input_image: "/path/to/product.jpg"
model: "BEN2"
output_dir: "/home/user/outputs"
output_name: "transparent_bg"
# 图片生成视频
run_image_to_video_workflow_wan2_2_14b_i2v:
input_image: "/path/to/landscape.jpg"
positive_prompt: "缓慢的云朵飘动，阳光穿过云层"
length: 81
fps: 16
output_dir: "/home/user/videos"
output_name: "animated_landscape"
# 音乐生成
run_text_to_audio_workflow_audio_ace_step_1_t2a_song:
tags: "anime, j-pop, female vocals, piano, emotional"
lyrics: "[verse]\n春の風が吹いて\n桜の花びら舞う\n[chorus]\n君と歩いた道\n忘れない思い出"
seconds: 120
output_dir: "/home/user/music"
output_name: "spring_song"
环境变量说明
| 变量 | 说明 | 默认值 |
|---|---|---|
WORKFLOWS_DIR | 工作流文件夹路径 | ./workflows |
COMFYUI_HOST | ComfyUI 服务器地址 | localhost |
COMFYUI_PORT | ComfyUI 服务器端口 | 8000 |
BYPASS_PROXY | 是否绕过系统代理 | true |
许可证
MIT