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.txt2） 启动ComfyUI
确保ComfyUI已安装并在本地运行。
cd
python main.py --port 81883） 运行MCP服务器
从存储库目录：
python server.py服务器在以下位置进行监听：
http://127.0.0.1:9000/mcp4） 验证其是否正常工作（不需要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_imageview_imageregenerateget_joblist_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")→ getsasset_id
代理人： *发布资产*
- 呼叫
publish_asset(asset_id="...", target_filename="hero.webp")→ 成功
用户： “现在生成一个徽标并将其作为‘站点徽标’添加到清单中”
代理人： *生成并发布清单*
- 呼叫
generate_image(prompt="a modern logo")→ getsasset_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.
______________________________________________________________________
详细参考
完整的参数列表、返回模式、配置选项和高级工作流元数据记录在：
项目结构
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