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 工作流

1. 在 ComfyUI 中创建或打开工作流
2. 点击菜单 → Save (API Format)
3. 保存 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：查找参数路径

1. 打开工作流 JSON 文件
2. 找到需要暴露的参数节点
3. 记录节点 ID 和输入字段名
4. 组合成路径格式：节点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 无法找到工具

1. 确认项目路径正确（使用绝对路径）
2. 检查 Claude 配置文件格式是否正确
3. 查看 Claude 的开发者工具日志

WSL2 连接问题

如果无法连接到 Windows 上的 ComfyUI：

1. 确保 ComfyUI 启动时使用 --listen 0.0.0.0 参数
2. 检查 Windows 防火墙是否允许端口访问
3. 运行 scripts/detect-wsl2-host.sh 重新检测 IP
4. 确保 BYPASS_PROXY=true 已设置

工作流加载失败

检查以下几点：

• 工作流文件夹名称与内部 JSON 文件名一致
• descriptor.json 格式正确
• JSON 路径与实际工作流结构匹配
• 查看控制台错误信息

npx 执行错误

如果 npx 无法执行：

# 确保使用绝对路径
npx /home/username/comfyui-mcp

# 或直接使用 node
node /home/username/comfyui-mcp/dist/index.js

工作原理

1. 工作流加载：启动时扫描 workflows 文件夹的分类目录，加载所有工作流
2. 工具注册：每个工作流注册为 run_{category}_workflow_{name} 格式的工具
   • 例如：run_text_to_image_workflow_flux_schnell
   • 例如：run_image_to_video_workflow_image_to_video_wan
3. 参数处理：接收输入参数，根据描述文件的路径映射修改工作流 JSON
4. 执行监控：通过 WebSocket 连接 ComfyUI，监听执行进度
5. 结果返回：执行完成后返回生成结果

示例工作流

项目包含多个分类的专业工作流：

文本生成图像 (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