ComfyUI MCP Server

ComfyUI MCP Server

通过自然对话生成和优化 AI 图像／音频／视频

一个轻量级 MCP（Model Context Protocol）服务，可让 AI Agent 使用本地 ComfyUI 实例生成图像、音频和视频，并进行迭代优化。

运行服务、连接客户端，然后调用工具即可。其他内容均为可选进阶信息。

---

快速开始（2–3 分钟）

确认一切正常运行。

1) 克隆并设置

git clone https://github.com/joenorton/comfyui-mcp-server.git
cd comfyui-mcp-server
pip install -r requirements.txt

2) 启动 ComfyUI

确保已安装 ComfyUI，且它正在本地运行。

cd <ComfyUI_dir>
python main.py --port 8188

3) 运行 MCP 服务

在仓库目录中：

python server.py

服务监听地址：

http://127.0.0.1:9000/mcp

4) 验证是否正常运行（无需 AI 客户端）

运行随附的测试客户端：

# Use default prompt
python test_client.py

# Or provide your own prompt
python test_client.py -p "a beautiful sunset over mountains"
python test_client.py --prompt "a cat on a mat"

test_client.py 将：

• 连接到 MCP 服务
• 列出可用工具
• 获取并显示服务默认值（宽度、高度、步数、模型等）
• 使用你的提示词（或默认提示词）运行 generate_image
• 自动为所有其他参数使用服务默认值
• 打印生成的资源信息

如果此步骤成功，说明系统已正常运行。

注意： 测试客户端会遵循通过配置文件、环境变量或 set_defaults 调用设置的服务默认值。只有 prompt 参数是必填项；其他所有参数都会自动使用服务默认值。

就是这样。

---

与 AI Agent 配合使用（Cursor / Claude / n8n）

服务运行后，即可将其连接到 AI 客户端。

创建项目范围的 .mcp.json 文件：

{
  "mcpServers": {
    "comfyui-mcp-server": {
      "type": "streamable-http",
      "url": "http://127.0.0.1:9000/mcp"
    }
  }
}

注意： 某些客户端使用 "type": "http"，而非 "streamable-http"。这两种方式都适用于此服务。如果自动发现无法正常工作，请尝试更改 type 字段。

重启 AI 客户端。现在，你可以调用以下工具：

• generate_image
• view_image
• regenerate
• get_job
• list_assets

这是主要的预期使用方式。

---

正常运行后可以做什么

确认服务正常运行且客户端可以连接后，系统支持：

• 通过 regenerate 进行迭代优化（无需重新输入提示词）
• 明确指定资源身份，确保后续操作可靠
• 为长时间运行的生成任务轮询状态并取消任务
• 可选地将图像注入 AI 的上下文（view_image）
• 自动发现 ComfyUI 工作流并公开其参数
• 配置默认值，避免重复设置常用参数

以下所有内容都基于你刚刚测试过的相同基本流程。

迁移说明（早期版本）

如果你用过此项目的早期版本，部分内容已有变化。

相同之处

• 仍然运行本地 MCP 服务，由它将执行任务委托给 ComfyUI
• 工作流仍是放在 workflows/ 目录中的 JSON 文件
• 图像生成的核心行为没有变化

新增内容

• Streamable HTTP 传输取代了旧版基于 WebSocket 的方式
• 显式任务管理（get_job、get_queue_status、cancel_job）
• 使用资源身份标识取代临时 URL（在主机名变更后仍保持稳定）
• 通过 regenerate 支持迭代（使用参数覆盖重新执行）
• 为 Agent 提供可选的视觉反馈（通过 view_image）
• 可配置的默认值，避免重复设置常用参数

概念上的变化

早期版本是一个轻量级的请求／响应桥接工具。 当前版本围绕迭代和有状态控制循环构建。

你仍可通过单次调用生成图像，但现在还可以：

• 引用特定输出
• 优化结果，而无需重新指定所有内容
• 轮询和取消长时间运行的任务
• 让 AI Agent 直接检查生成的图像

想要使用旧版行为？

如果你想采用早期版本中精简的单次生成方式：

• 运行 test_client.py（它沿用了原始使用模式）
• 只用提示词调用 generate_image（其余参数由服务默认值处理）
• 忽略其他工具

除非你想使用新增功能，否则无需迁移。

可用工具

生成工具

• generate_image：生成图像（需要 prompt）
• generate_song：生成音频（需要 tags 和 lyrics）
• regenerate：使用可选的参数覆盖值重新生成现有资源（需要 asset_id）

查看工具

• view_image：内嵌查看生成的图像（仅限图像，不支持音频/视频）

任务管理工具

• get_queue_status：检查 ComfyUI 队列状态（运行中/待处理的任务）——提供异步状态感知
• get_job：通过 prompt_id 轮询任务完成状态，检查任务是否已完成
• list_assets：浏览最近生成的资源——支持 AI 记忆和迭代
• get_asset_metadata：获取资源的完整来源信息和参数——包含工作流历史
• cancel_job：取消排队中或正在运行的任务

配置工具

• list_models：列出可用的 ComfyUI 模型
• get_defaults：获取当前默认值
• set_defaults：设置默认值（可选择是否持久保存）

工作流工具

• list_workflows：列出所有可用的工作流
• run_workflow：使用自定义参数运行任意工作流

发布工具

• get_publish_info：显示发布状态（检测到的项目根目录、发布目录、ComfyUI 输出根目录，以及任何缺失的配置）
• set_comfyui_output_root：设置 ComfyUI 输出目录（推荐用于 Comfy Desktop / 非标准安装；重启后仍会保留）
• publish_asset：将生成的资源发布到项目的 Web 目录，并进行确定性压缩（默认 600KB）

发布说明：

• 限定于当前会话：asset_id 仅在当前服务会话中有效；重启后会失效。
• 常见情况无需配置：自动检测发布目录（public/gen、static/gen 或 assets/gen）；如果无法检测到 ComfyUI 输出目录，可通过 set_comfyui_output_root 设置一次。
• 两种模式：演示模式（显式指定文件名）和资源库模式（自动生成文件名并更新清单）。资源库模式下必须提供 manifest_key。
• 清单：仅在提供 manifest_key 时更新。
• 压缩：使用确定性的阶梯式压缩来满足大小限制；如果无法达到限制，会返回清晰的错误信息。

快速入门：

Agent 对话流程示例：

用户：“为我的网站生成一张主视觉图，并将其发布为 hero.webp”

**Agent：**检查发布配置

• 调用 get_publish_info() → 状态显示为“ready”

**Agent：**生成图像

• 调用 generate_image(prompt="a hero image for a website") → 获取 asset_id

**Agent：**发布资源

• 调用 publish_asset(asset_id="...", target_filename="hero.webp") → 成功

用户：“现在生成一个徽标，并将其以 'site-logo' 为键添加到清单中”

**Agent：**生成并发布，同时更新清单

• 调用 generate_image(prompt="a modern logo") → 获取 asset_id
• 调用 publish_asset(asset_id="...", manifest_key="site-logo") → 自动生成文件名并更新清单

详细用法和测试说明请参阅 docs/HOW_TO_TEST_PUBLISH.md。

自定义工作流

将 JSON 文件放入 workflows/ 目录即可添加自定义工作流。系统会自动发现这些工作流，并将其作为 MCP 工具提供。

工作流占位符

在工作流 JSON 中使用 PARAM_* 占位符来公开参数：

• PARAM_PROMPT → prompt: str（必填）
• PARAM_INT_STEPS → steps: int（可选）
• PARAM_FLOAT_CFG → cfg: float（可选）

示例：

{
  "3": {
    "inputs": {
      "text": "PARAM_PROMPT",
      "steps": "PARAM_INT_STEPS"
    }
  }
}

工具名称根据文件名生成（例如，my_workflow.json → my_workflow 工具）。

---

配置

服务器支持可配置的默认值，避免重复填写常用参数。可通过以下方式设置默认值：

• 运行时默认值：使用 set_defaults 工具（临时设置，重启后丢失）
• 配置文件：~/.config/comfy-mcp/config.json（持久保存）
• 环境变量：以 COMFY_MCP_DEFAULT_* 为前缀的变量

默认值按以下优先级解析：单次调用的值 → 运行时默认值 → 配置文件 → 环境变量 → 硬编码默认值。

完整配置详情请参阅 docs/REFERENCE.md。

---

详细参考

完整的参数列表、返回架构、配置选项和高级工作流元数据，请参阅：

• API 参考 - 完整的工具参考、参数、返回值和配置
• 架构 - 设计决策和系统概览

项目结构

comfyui-mcp-server/
├── server.py              # Main entry point
├── comfyui_client.py      # ComfyUI API client
├── asset_processor.py     # Image processing utilities
├── test_client.py         # Test client
├── managers/              # Core managers
│   ├── workflow_manager.py
│   ├── defaults_manager.py
│   └── asset_registry.py
├── tools/                 # MCP tool implementations
│   ├── generation.py
│   ├── asset.py
│   ├── job.py             # Job management tools
│   ├── configuration.py
│   └── workflow.py
├── models/                # Data models
│   ├── workflow.py
│   └── asset.py
└── workflows/             # Workflow JSON files
    ├── generate_image.json
    └── generate_song.json

备注

• 服务器默认绑定到 localhost。未经身份验证或未配置反向代理，请勿将其公开暴露。
• 确保模型位于 <ComfyUI_dir>/models/checkpoints/ 中
• 服务器使用 streamable-http 传输方式（基于 HTTP，而非 WebSocket）
• 工作流会自动发现，无需更改代码
• 资源在 24 小时后过期（可配置）
• view_image 仅支持图像（PNG、JPEG、WebP、GIF）
• 资源身份使用 (filename, subfolder, type) 而非 URL，以提高可靠性
• 系统会保存完整的工作流历史，以便追溯来源并复现
• regenerate 使用已存储的工作流数据重新生成资源，并支持覆盖参数
• 会话隔离：list_assets 可按会话筛选，保持 AI Agent 上下文整洁

故障排除

服务器无法启动：

• 检查 ComfyUI 是否正在 8188 端口（默认端口）上运行
• 确认已安装 Python 3.8+（python --version）
• 检查是否已安装所有依赖项：pip install -r requirements.txt
• 查看服务器日志中的具体错误消息

客户端无法连接：

• 确认控制台显示“Server running at http://127.0.0.1:9000/mcp”
• 直接测试服务器：curl http://127.0.0.1:9000/mcp（应返回 MCP 响应）
• 检查项目根目录中是否有 .mcp.json（或客户端所需的正确位置）
• 尝试使用 "type": "streamable-http" 和 "type": "http"，两者均受支持
• Cursor 特定问题请参阅 docs/MCP_CONFIG_README.md

工具未显示：

• 检查 workflows/ 目录中是否有包含 PARAM_* 占位符的 JSON 文件
• 查看服务器日志中的工作流解析错误
• 确认 ComfyUI 已安装所需的自定义节点（如果使用自定义工作流）
• 添加新工作流后，重启 MCP 服务

找不到资源错误：

• 资源默认在 24 小时后过期（可通过 COMFY_MCP_ASSET_TTL_HOURS 配置）
• 服务器重启后资源会丢失（这是临时设计）
• 使用 get_asset_metadata 确认资源存在后，再使用 regenerate
• 查看服务器日志，确认资源是否已成功注册

已知限制（v1.0）

• 临时资源注册表：asset_id 引用仅在 MCP 服务运行期间（且未超过 TTL）有效。重启后，先前签发的 asset_id 将无法解析，这些资源的 regenerate 操作也会失败。

贡献

欢迎提交问题和拉取请求！开发指南请参阅 CONTRIBUTING.md。

致谢

• @venetanji - streamable-http 基础与 PARAM_* 系统

维护者

@joenorton

许可证

Apache License 2.0