ComfyUI_MCP Server（ComfyUI的ModelContextProtocol 服务端 | ModelContextProtocol Server for ComfyUI）

ComfyUI_MCP Server（ComfyUI 的 ModelContextProtocol 服务端 | ComfyUI 的 ModelContextProtocol 服务端）

项目简介 | 项目简介

ComfyUI_MCP Server 是为 ComfyUI 设计的松耦合、可扩展、配置驱动的 ModelContextProtocol（模型上下文协议）服务端。支持根据客户定制的工作流扩展 MCP 服务（工具），如 txt2img、img2img。每个 MCP 服务（工具）的参数和行为均可通过 JSON 初始化和 MCP 工具装饰器模块灵活扩展，适用于 AI 绘图、推理等场景的自动化与集成。

ComfyUI_MCP Server 是为 ComfyUI 设计的松耦合、可扩展、配置驱动的 Model Context Protocol（MCP）服务端。它支持根据用户定制的工作流扩展 MCP 服务（工具），如 txt2img 和 img2img。每个 MCP 服务（工具）的参数和行为均可通过 JSON 初始化和 MCP 工具装饰器模块灵活扩展，因此非常适合用于 AI 图像生成、推理及类似场景的自动化与集成。

视频演示 | 视频演示

🎬 ComfyUI_MCP Server 功能演示（YouTube）

---

目录结构 | 目录结构

mcp_server/
├── mcp_server/
│   ├── mcpserver.py         # 主入口，自动注册 tools 目录下所有工具 | Main entry, auto-registers all tools in the tools directory
│   ├── tools/               # 工具模块与mcp tool配置（每个mcp tool一个py和json）| Tool modules and configs (one .py and .json per mcp tool)
│   │   ├── txt2img.py
│   │   ├── txt2img_api.json
│   │   ├── img2img.py
│   │   ├── img2img_api.json
│   │   ├── {xxxx}.py        # 配合被调用的ComfyUI的工作流。可任意添加MCP工具配置，工具自动注册与API扩展机制。  
│   │   ├── {xxxx}_api.json  # Used in conjunction with the workflows of the callable ComfyUI, allowing for the addition of MCP tool configurations, with automatic registration and API extension mechanisms.
│   │   ├── ......
│   │   └── __init__.py
│   ├── utils.py             # 配置、模板、随机种子等通用工具 | Utilities for config, templates, random seed, etc.
│   ├── config.ini           # mcp服务与被调用的ComfyUI地址配置 | Service and ComfyUI address config
│   ├── logger.py & decorator.py                # 日志系统 | logs sys
│   └── __init__.py
├── workflows/               # MCP工具可实现的ComfyUI工作流json，与tools/对应。 | The "ComfyUI workflow json" that the "MCP tool" can achieve. Corresponding to "tools/".
│   ├── txt2img.json
│   ├── img2img.json
│   ├── {xxxx}.json          
│   ├── ......
├── pyproject.toml           # 构建配置与依赖 | Build config and dependencies
└── README.md                # 使用说明（本文件）| User guide (this file)

---

安装 & 配置 & 运行 | 安装 & 配置 & 运行

python install.py # install(check item 2~3) & config(check item 1) 

run_mcp.bat #run on windows
./run_mcp.sh #run on linux

• 默认以流式 HTTP（streamable-http）模式运行 | 默认以 streamable-http 模式运行
• 自动注册 tools/ 目录下的所有工具模块 | 自动注册 tools/ 目录下的所有工具模块

---

ComfyUI_MCP 工具自动注册与 API 扩展机制 | 工具自动注册与 API 扩展

1. 新增自定义 MCP 工具和方法实现 | 添加自定义 MCP 工具和方法实现

以 txt2img 为例，扩展新工具只需：

• 新增 tools/myapi.py，实现 register_myapi_tool(mcp) 并注册 MCP 服务（工具）
• 新增 tools/myapi_api.json，定义参数模板（从目标 ComfyUI 实例的自定义工作流中导出同名 API，并添加 _api 后缀）
• 无需修改主入口，自动生效

新增工具（例如 txt2img）：

• 新增 tools/myapi.py，实现 register_myapi_tool(mcp) 并注册 MCP 服务（工具）
• 新增 tools/myapi_api.json 以定义参数模板（从目标 ComfyUI 实例的自定义工作流中导出同名 API，并添加 _api 后缀）
• 无需修改主入口，即可自动生效

典型方法实现与返回格式 | 典型用法与返回格式

文生图（txt2img）| 文生图（txt2img）

# tools/txt2img.py 
def register_txt2img_tool(mcp):
    async def comfyui_txt2img_impl(prompt: str, pic_width: str, pic_height: str, negative_prompt: str, batch_size: str, model: str) -> str:
      ...
# 返回图片 Markdown 格式 | Returns image in Markdown format
      ...
        markdown_images = [f"![image]({url})" for url in image_urls]
        return "\n".join(markdown_images)

• 调用 ComfyUI 在线工作流 HTTP API 获取结果。 | 调用 ComfyUI 在线工作流 HTTP API 获取结果。
• 所有参数均可省略，默认值取自对应的 JSON 文件 tools/txt2img_api.json | 所有参数均可选；默认值取自对应的 JSON 文件 tools/txt2img_api.json。
• 返回图片 Markdown 链接，可直接用于文档或前端展示 | 返回图片 Markdown 链接，可直接用于文档或前端展示
• 再将以上功能封装成对应的 MCP 服务（工具） | 然后将以上功能封装成对应的 MCP 服务（工具）。

---

2. MCP 工具自动注册 | MCP 工具自动注册

• mcpserver.py 会自动遍历 tools/ 目录下的所有 .py 文件（如 txt2img.py），并调用其中的 register_xxx_tool(mcp) 注册函数。

• 每个工具模块都需实现 register_xxx_tool(mcp)，并通过 @mcp.tool() 装饰器注册 MCP 服务（工具）。

• mcpserver.py 会自动遍历 tools/ 目录下的所有 .py 文件（如 txt2img.py），并调用其中的 register_xxx_tool(mcp) 注册函数。

• 每个工具模块都必须实现 register_xxx_tool(mcp)，并通过 @mcp.tool() 装饰器注册 MCP 服务（工具）。

示例：

# tools/txt2img.py
def register_txt2img_tool(mcp):
    @mcp.tool()
    async def txt2img(prompt: str, pic_width: str = '512', ... ) -> str:
        ...

3. 配置驱动参数 | 配置驱动参数

• 每个 MCP 服务（工具）的参数签名、类型和注释均可通过同名 JSON（如 tools/txt2img_api.json）自动生成。在被调用的 ComfyUI 自定义工作流中导出同名 API，并添加后缀_api。

• MCP 服务（工具）的参数均为可选；未传入时使用模板默认值。支持递归随机化 seed、模型白名单、batch_size 限制等业务规则。

• 新增 MCP 服务（工具）时，JSON 模板应从目标 ComfyUI 实例的自定义工作流中导出，使用同名 API 并添加后缀 _api，然后放置于 tools 目录。

• 每个 API 的参数签名、类型和文档字符串均可通过同名 JSON（例如 tools/txt2img_api.json）自动生成。

• MCP 服务（工具）的参数均为可选；如果未提供，则使用模板中的默认值。支持递归随机化 seed、模型白名单、batch_size 限制等业务规则。

• 对于新的 MCP 服务（工具），应从目标 ComfyUI 实例的自定义工作流中导出 JSON 模板，使用同名 API 并添加后缀 _api，然后放置于 tools 目录。

示例片段 tools/txt2img_api.json | 示例片段：

{
  "5": {
    "inputs": {
      "width": 512,
      "height": 512,
      "batch_size": 1
    },
    "class_type": "EmptyLatentImage"
  }
}

4. 资源注册与管理 | 资源注册与管理

支持通过 @mcp.resource("info//ckpt") 装饰器注册资源型 API，实现如模型等资源的自动发现与管理。

支持通过 @mcp.resource("info//ckpt") 装饰器注册资源型 API，从而自动发现和管理模型等资源。

示例 | 示例：

@mcp.resource("info//ckpt")
async def list_checkpoints() -> list:
    # 返回所有可用的ckpt模型列表
    ...

---

使用 MCP Inspector 进行调试 | 使用 MCP Inspector 调试

MCP Inspector 是官方推荐的交互式开发者工具，可用于测试和调试 MCP 服务端。

MCP Inspector 是官方推荐的交互式开发者工具，可用于测试和调试 MCP 服务端。

• 官方文档 | 官方文档：https://modelcontextprotocol.io/docs/tools/inspector

快速启动 Inspector | 快速启动 Inspector

run_mcp.bat --inspector #run on windows
./run_mcp.sh --inspector #run on linux

• Inspector 可以连接本地 MCP 服务，支持对工具、资源、提示词等进行全面的交互测试。

• 可在 Inspector 的 Tools 面板中查看所有自动注册的 API 工具、测试参数、查看返回结果并调试异常。

• Inspector 可以连接本地 MCP 服务，支持对工具、资源、提示词等进行全面的交互测试。

• 你可以在 Inspector 的 Tools 面板中查看所有自动注册的 API 工具、测试参数、查看结果并调试异常。

更多用法详见 官方 Inspector 指南 | 查看官方 Inspector 指南。

---

常见问题 | 常见问题

• ComfyUI 未启动或地址错误：请检查 config.ini 配置

• 依赖未安装：请先执行 uv pip install -r pyproject.toml

• 新增工具未生效：确认已实现 register_xxx_tool(mcp) 并放置于 tools/ 目录

• 参数校验失败：请检查 JSON 模板与实际参数类型、范围。（从被调用的 ComfyUI 自定义工作流中导出同名 API 并添加后缀_api，然后放置于 tools/ 目录）

• Inspector 无法连接：确认 MCP 服务已启动且端口未被占用

• 日志未生成或无输出：请检查 config.ini 中的 logging 配置项，确保 log_path 路径存在且有写入权限。

• MCP 服务传输模式切换无效：请确认已正确修改 config.ini 中的 transport 参数，并重启服务。

• ComfyUI 未启动或地址错误：请检查 config.ini

• 依赖未安装：请先执行 uv pip install -r pyproject.toml

• 新增工具未生效：确保已实现 register_xxx_tool(mcp) 并放置于 tools/ 目录

• 参数校验失败：请检查 JSON 模板和实际参数的类型与范围。（从目标 ComfyUI 实例的自定义工作流中导出同名 API 并添加 _api 后缀，然后放置于 tools/ 目录）

• Inspector 无法连接：确保 MCP 服务正在运行且端口未被占用

• 未生成日志或无输出：请检查 config.ini 中的 logging 配置，确保 log_path 路径存在且具有写入权限。

• MCP 服务传输模式切换无效：请确认已正确修改 config.ini 中的 transport 参数，并重启服务。

---

贡献与扩展 | 贡献与扩展

欢迎提交 PR 或 issue，完善更多 API 工具与业务逻辑。 如需集成更多模型、参数或业务规则，仅需新增/修改工具模块与 JSON 配置，无需侵入主流程。

欢迎通过 PR 或 issue 贡献，完善更多 API 工具和业务逻辑。 如需集成更多模型、参数或业务规则，只需新增/修改工具模块与 JSON 配置，无需更改主流程。

---

待优化 | 待办事项

• 参数类型自动推断与校验增强：支持更智能的参数类型推断和更严格的校验，提升健壮性。

  增强参数类型推断与校验：通过更智能的类型推断和更严格的校验提升健壮性。

• 更丰富的错误处理与日志：增加详细的错误日志、异常追踪和用户友好提示。

  丰富错误处理与日志：提供更详细的错误日志、异常追踪和便于用户理解的提示。

• 热加载工具/配置：支持tools目录和配置文件的热加载，无需重启服务即可生效。

  工具/配置热加载：支持热加载tools目录和配置文件，无需重启服务即可生效。

• 多ComfyUI后端支持：支持同时连接和调度多个ComfyUI后端实例，实现负载均衡或多模型推理。

  多ComfyUI后端支持：支持同时连接和调度多个ComfyUI后端实例，实现负载均衡或多模型推理。

• 多媒体数据交互支持：支持图片、声音、视频等多媒体数据的输入输出与处理。

  多媒体数据交互支持：支持图片、音频、视频等多媒体数据的输入、输出和处理。

• 更全面的ComfyUI HTTP API的集成。

  更全面地集成ComfyUI HTTP API。

• 单元测试与CI完善：补充更多单元测试用例，集成持续集成（CI）流程，保障代码质量。

  完善单元测试与CI：增加更多单元测试用例，并集成CI流程以保障代码质量。