ComfyUI-MCP-Server - ComfyUI Model Context Protocol Integration

[简体中文] [ENGLISH]

[!NOTE] ⭐ 如果您喜欢该项目或觉得有帮助，请给项目点一个 Star，您的支持是我们持续改进的动力！

ComfyUI-MCP-Server 是一个基于 MCP（Model Context Protocol / 模型上下文协议）的服务器实现，将 ComfyUI 中用户定义的工作流转化为参数可配置的 MCP 工具，供 AI 代理（Agents）直接使用。

本项目提供 Python 与 TypeScript 两个独立语言版本，功能基本对等，可按需选用：

注：Python 版本带有更多实验性功能，TypeScript 版本则更稳定。

📋 项目功能

通过本项目，您可以通过连接ComfyUI从而赋予 AI 助手（如 Claude Desktop、Trae、Dify 等）强大的多媒体生成能力：

✨ 项目特色

• 🔌 工作流即工具：将 ComfyUI 的节点图抽象为可供Agent使用的工具。
• 🎛️ 自定义参数暴露：可在工作流中精确定义哪些参数对外可见，限定 AI 在暴露范围内操作，防止模型幻觉与误操作。
• 🔧 零侵入接入：无需修改 ComfyUI 本体或安装任何必要插件，部署即连，开箱即用。
• 📥 自定义工作流导入：可手动导入 API 格式的工作流 JSON 文件，通过校验后即刻对 Agent 可用，无需重启服务。
• 📂 资产管理：支持从本地路径或网络 URL 自动上传资源至 ComfyUI。
• ⚡ 流式与进度支持：支持生成进度报告（需 Client/Host 支持）。
• 🌍 国际化双语支持：内置中英文（zh-CN/en）国际化。
• 🧩 标准 MCP 适配：全面支持 STDIO 与 Streamable HTTP 通信协议。
• 🔬 Skills 支持：包含项目技能手册SKILL.md，针对支持 Skills 的 AI 助手通过 Skills 进行深度优化。

更多详情可查阅 为什么选择我们

🧰 可用工具集

AI 代理可以通过 MCP 协议调用以下内置工具：

🏆 为什么选择我们？

更多详情可查阅 为什么选择我们

🎬 演示视频

默认方式

点击下方图片观看演示视频。

API_JSON 方式

点击下方图片观看演示视频。

🚀 快速开始

仅需两步，快速启动项目。

提醒：安装启动项目后，还需查阅[使用教程]，否则无法使用工作流相关功能。

准备工作（必需）

在启动本项目之前，请确保您的系统中已安装以下软件

• Node.js 18+ [官方链接]
• ComfyUI 0.9.1+ [官方链接]
• MCP 客户端/AI Agent，例如Claude Desktop、Cursor等

第一步：安装项目与依赖

1. 克隆本项目 在终端中执行以下命令：

git clone https://github.com/MetaBrain-Labs/ComfyUI-MCP-Server-TypeScript.git

2. 移动到项目目录

cd ComfyUI-MCP-Server-TypeScript

3. 安装依赖

npm install

第二步：配置环境与启动项目

1. 项目环境配置

进入项目根目录，根据系统实际情况修改 .env 文件中的配置。 详细配置说明请查阅：[环境变量]

2. 连接并运行项目

根据您的需求选择传输方式以启动项目：

[!TIP] MCP传输机制

MCP 协议目前定义了两种客户端-服务器通信的标准传输机制：

• STDIO
• Streamable HTTP

本项目两者皆支持，请根据您的 MCP 客户端能力进行选择。

您有责任确保使用这些服务器符合相关条款，以及适用于您的任何法律、规则、法规、政策或标准。

模式一：STDIO 连接 (推荐用于 Claude Desktop 等本地客户端)

• MCP客户端启动： 复制下述 JSON 文件，在 MCP 客户端的 MCP 配置中粘贴并修改即可。

  [!NOTE]

  部分 MCP 客户端配置 MCP Server 的方法请查阅：[示例]

  其他项目设置请在环境变量中修改，参数详情请查阅：[环境变量]

  如果 ComfyUI 在云端运行，请将 "SYNC_MODE" 设置为 "manual"

  config.json

  Copy

  {
    "mcpServers": {
      "comfy-ui-advanced": {
        "command": "npx",
        "args": [
          "tsx",
          "<项目根目录绝对路径，如 D:/ComfyUI-MCP-Server-TypeScript>"
        ],
        "env": {
          "LOCALE": "en",
          "MCP_SERVER_URL": "http://127.0.0.1:8189/mcp",
          "MCP_SERVER_IP": "127.0.0.1",
          "MCP_SERVER_PORT": "8189",
          "COMFY_UI_SERVER_IP": "http://127.0.0.1:8188",
          "COMFY_UI_SERVER_HOST": "127.0.0.1",
          "COMFY_UI_SERVER_PORT": "8188",
          "SYNC_MODE": "timed",
          "SYNC_POLL_INTERVAL_SECONDS": "3",
          "SYNC_EVENT_FALLBACK_INTERVAL_SECONDS": "300",
          "ONDEMAND_REFRESH_COOLDOWN_SECONDS": "3",
          "COMFY_UI_INSTALL_PATH": "",
          "WORKFLOW_NAME_REGEX": "^==(.+?)==$",
          "WORKFLOW_PARAM_REGEX": "^=>(.+)$",
          "LOG_LEVEL": "INFO"
        }
      }
    }
  }
  

• 终端启动：
  bash

  Copy

  # 终端连接启动方式无需配置json，直接在项目根目录下执行：
  npm run dev
  

模式二：StreamHTTP 连接 (推荐用于网络化/分布式部署)

• MCP客户端启动： StreamHTTP 的项目设置在 [.env] 中指定，无需在下述 JSON 中配置。

  [!NOTE]

  部分 MCP 客户端配置 MCP Server 的方法请查阅：[示例]

  目前支持 StreamHTTP 的 MCP Client/Host 较少，请根据需求使用。

  如果 ComfyUI 在云端运行，请在 [.env] 中将 "SYNC_MODE" 设置为 "manual"

  config.json

  Copy

  {
    "mcpServers": {
      "comfy-ui-advanced-http": {
        "url": "http://127.0.0.1:8189/mcp"
      }
    }
  }
  

• 终端启动：
  bash

  Copy

  # 启动 Streamable HTTP
  npm run dev
  

至此，项目部署且启动完成。若您需要调试工具，请继续阅读下文，否则请直接跳转至[使用教程]。

调试工具 (MCP Inspector)

Inspector是MCP官方提供的MCP调试工具，推荐使用StreamHTTP作为Inspector的连接方式。

• 克隆项目
• 安装相关依赖
  Terminal

  Copy

  npm install
  

• 启动StreamHTTP连接方式的Server：
  bash

  Copy

  # 1. 在终端 A 启动 HTTP 服务
  npm run dev
  

• 启动Inspector：
  bash

  Copy

  # 2. 在终端 B 启动 Inspector
  npm run inspector
  

启动完成后，控制台中会出现类似下述地址，复制地址到浏览器后即可开始调试相关工具：

# 每次启动MCP_PROXY_AUTH_TOKEN都不一样，因此每次启动后需要及时切换链接
http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=d66fcf6cbbb3723c60bfef51f020e5e96811002a675e7162b065b44f2fe377f3

inspector启动成功后，浏览器页面配置参考：

📖 使用教程

本项目需要对 ComfyUI 工作流进行简单的特定标记，以使 AI Agent 能够准确识别和调用，可以通过以下两种方式添加可用工作流：

标记规则（必须了解）

无论使用哪种方式添加可用工作流，都必须在其工作流中添加以下标记节点：