Comfyui MCP Server (comfyui-mcp-server)

ComfyUI MCP服务器

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

一个轻量级的MCP（模型上下文协议）服务器，允许AI代理使用本地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 
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代理（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"。两者都适用于此服务器。如果自动发现不起作用，请尝试更改类型字段。

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

• generate_image
• view_image
• regenerate
• get_job
• list_assets

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

______________________________________________________________________

它工作后你能做什么

一旦您确认服务器运行并且客户端可以连接，系统支持：

• 通过迭代细化 regenerate （无重新提示）
• 明确的资产标识，以便进行可靠的跟进
• 针对长时间运行的几代人的作业轮询和取消
• 可选的图像注入到AI的上下文中(view_image)
• 自动发现带有参数暴露的ComfyUI工作流
• 可配置的默认值，以避免重复常见设置

下面的所有内容都基于您刚才测试的相同基本循环。

迁移说明（以前版本）

如果您使用过此项目的早期版本，则会发生一些变化。

有什么相同之处

• 您仍然运行一个本地MCP服务器，该服务器将执行委托给ComfyUI
• 工作流仍然是放置在 workflows/ 目录
• 图像生成行为的核心不变

有什么新消息

• 可流式HTTP传输 替换旧的基于WebSocket的方法
• 明确的作业管理 (get_job, get_queue_status, cancel_job)
• 资产标识 而不是临时URL（在主机名更改时稳定）
• 迭代支持 通过 regenerate （使用参数覆盖进行回放）
• 可选视觉反馈 代理商通过 view_image
• 可配置的默认值 避免重复常见参数

概念上发生了什么变化

早期版本是一个精简的请求/响应桥。 当前版本是围绕 迭代 和 有状态控制回路.

您仍然可以通过一次调用生成图像，但现在您可以选择：

• 返回具体输出
• 在不重新指定所有内容的情况下优化结果
• 轮询和取消长时间运行的作业
• 让AI代理直接检查生成的图像

寻找旧的行为？

如果你想从早期版本中获得最小的单次射击行为：

• 跑 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：使用确定性压缩（默认600KB）将生成的资产发布到项目的web目录中

发布注释：

• 会话范围: asset_ids仅对当前服务器会话有效；重新启动会使它们无效。
• 常见情况下无需配置：自动检测到发布目录(public/gen, static/gen，或 assets/gen)；如果无法检测到ComfyUI输出，请通过设置一次 set_comfyui_output_root.
• 两种模式：演示（显式文件名）和库（自动文件名+清单更新）。在库模式下， manifest_key 是必需的。
• 清单：仅在以下情况下更新 manifest_key 提供。
• 压缩：满足尺寸限制的确定性阶梯；如果不能，则会出现明显的错误。

快速入门：

代理对话流示例：

用户： “为我的网站生成一个英雄图片，并将其发布为hero.webp”

代理人： *检查发布配置*

• 呼叫 get_publish_info() → 看到状态“就绪”

代理人： *生成图像*

• 呼叫 generate_image(prompt="a hero image for a website") → gets asset_id

代理人： *发布资产*

• 呼叫 publish_asset(asset_id="...", target_filename="hero.webp") → 成功

用户： “现在生成一个徽标并将其作为‘站点徽标’添加到清单中”

代理人： *生成并发布清单*

• 呼叫 generate_image(prompt="a modern logo") → gets asset_id
• 呼叫 publish_asset(asset_id="...", manifest_key="site-logo") → 自动生成文件名，更新清单

看 docs/HOW_TO_TEST_PUBLISH.md 了解详细的使用和测试说明。

自定义工作流

通过将JSON文件放置在 workflows/ 目录。工作流被自动发现并作为MCP工具公开。

工作流占位符

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

• 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_* 前缀变量

默认值按优先级顺序解决：每次调用值→ 运行时默认值→ 配置文件→ 环境变量→ 硬编码默认值。

有关完整的配置详细信息，请参阅 文档/参考.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。在没有身份验证或反向代理的情况下，不要公开它。
• 确保您的模型存在于 /models/checkpoints/
• 服务器使用 可流式传输http 传输（基于HTTP，不是WebSocket）
• 工作流是自动发现的，不需要更改代码
• 资产在24小时后过期（可配置）
• view_image 仅支持图像（PNG、JPEG、WebP、GIF）
• 资产身份使用 (filename, subfolder, type) 而不是URL以增强健壮性
• 存储完整的工作流历史记录，以便于来源和再现
• regenerate 使用存储的工作流数据重新创建具有参数覆盖的资产
• 会话隔离： list_assets 可以按会话筛选干净的AI代理上下文

故障排除

服务器无法启动：

• 检查ComfyUI是否在端口8188上运行（默认）
• 验证是否安装了Python 3.8+(python --version)
• 检查是否安装了所有依赖项： pip install -r requirements.txt
• 检查服务器日志中的特定错误消息

客户端无法连接：

• 验证服务器是否显示“服务器正在运行http://127.0.0.1:9000/mcp“在控制台中
• 直接测试服务器： curl http://127.0.0.1:9000/mcp （应返回MCP响应）
• 检查 .mcp.json 位于项目根目录（或您的客户的正确位置）
• 两者都试试 "type": "streamable-http" 和 "type": "http" -两者均受支持
• 有关游标特定的问题，请参阅 docs/MCP_CONFIG_README.md

工具未出现：

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

未找到资产错误：

• 资产默认在24小时后过期（可通过配置 COMFY_MCP_ASSET_TTL_HOURS)
• 服务器重启时资产丢失（设计上是短暂的）
• 使用 get_asset_metadata 使用前验证资产是否存在 regenerate
• 检查服务器日志，查看资产是否已成功注册

已知限制（v1.0）

• 临时资产登记处: asset_id 引用仅在MCP服务器运行时有效（直到TTL到期）。重新启动后，以前发布过 asset_ids无法解决，这些资产的重新生成将失败。

贡献

欢迎问题和拉取请求！看 贡献.md 发展指南。

致谢

• @威尼斯坦吉 -流式http基础&PARAM\_\*系统

维护者

@乔诺顿

许可证

Apache许可证2.0