Comfyui MCP Server

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"

  {

"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" } } } }

- **终端启动：**

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

npm run dev

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

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

[!NOTE]

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

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

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

  {

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

- **终端启动：**

  # 启动 Streamable HTTP

npm run dev

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

调试工具 (MCP Inspector)

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

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

  npm install

• 启动StreamHTTP连接方式的Server：

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

npm run dev

- 启动Inspector：

  # 2. 在终端 B 启动 Inspector

npm run inspector

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

# 每次启动MCP_PROXY_AUTH_TOKEN都不一样，因此每次启动后需要及时切换链接

http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=d66fcf6cbbb3723c60bfef51f020e5e96811002a675e7162b065b44f2fe377f3

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

📖 使用教程

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

标记规则（必须了解）

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

1. 定义工具名称与功能描述（必须）

• 新建一个 PrimitiveNode (基础节点) 或 PrimitiveStringMultiline (多行字符串节点)，无需与任何节点连线。
• 双击修改节点标题为 ==您的工作流名称==（例：==生图-文生图==）。注意：这是 AI Agent 将看到的工具名，必须确保唯一。
• 在该节点的文本输入框中，写下这段工作流的功能描述（例："这是一个基础文生图流程，适合生成二次元图片"）。描述越清晰，AI 越能准确判断何时调用。

[!TIP]

自动过滤： 本项目会自动忽略没有 ==Workflow Name== 格式的工作流，确保 AI 只在划定的安全范围内操作，避免模型幻觉。

2. 暴露可自主修改的参数（可选）

• 如果您希望 AI 可以动态修改某些节点属性（例如：正向提示词、长宽尺寸、随机种子），需要暴露其参数。
• 找到目标节点（如：CLIP Text Encode (Prompt) 节点）。
• 双击修改其标题为 =>参数描述（例：=>正向提示词 或 =>生成的图片宽度）。
• 保存后，本服务器会自动将其解析为 MCP 工具的可变参数，AI 调用时将能按需填入值。

[!TIP]

自动过滤： 本项目会自动忽略没有 => 标题前缀的其它全部常规节点参数及节点连接相关参数，确保 AI 只在划定的安全范围内操作，避免模型幻觉。

---

方式一：在 ComfyUI 画布中设置（推荐）

适用于正在运行 ComfyUI 且支持新版工作流保存机制的用户：

1. 在 ComfyUI 中按照上述标记规则整理好节点。
2. 点击 ComfyUI 面板上的 Save (保存) 按钮。

建议在保存后，先自行点击一次 Queue Prompt (运行) 测试，确保工作流能够正常跑通。

1. 工作流将被保存至 ComfyUI 的用户数据目录（通常为 userdata/workflows/）。
2. 工作流生效时间视 `SYNC_MODE` 配置而定：

• timed 模式（默认）：MCP 服务器会在后台定时轮询，自动发现新保存的工作流，并在自动校验通过后立即挂载成 AI Agent 可用的工具。
• manual 模式：仅当 AI Agent 尝试调用工具库时才触发一次按需扫描。
• push 模式（实验性功能）：需配合 ComfyUI 插件，可实现保存后实时主动推送到服务器。

方式二：手动导入 API 格式 JSON 文件

适用于外部导入工作流或直接编写纯 API 格式（API Format）的工作流文件：

1. 准备好您的 ComfyUI API 格式 JSON 文件。
2. 使用文本编辑器打开该 JSON 文件，添加以下内容以符合核心标记规则：

• 工具名称： 在任意位置添加以下内容：

    "99": {

"inputs": { "value": "功能描述" }, "class_type": "PrimitiveStringMultiline", "_meta": { "title": "==工作流名称==" } }

"99" 仅为示例，实际使用时请使用未被占用的节点 ID。

添加完毕后请检查json格式是否正确，每个节点后都需添加逗号，否则将导致工作流无法使用。

• 暴露参数： 找到需要让 AI 修改的参数所在的节点，添加或修改 _meta 对象中的 "title": "=>参数描述"。

1. 将修改后的 JSON 文件直接放入本项目的 workflow/ 目录下（如果该目录不存在，请手动创建）。
2. 工作流生效机制与上述相同，依据 SYNC_MODE 模式：

• timed 模式（默认）：MCP 服务器将定时扫描该目录，自动解析参数并完成挂载。
• manual / push 模式：工作流将在 AI Agent 下次请求工作流或执行工具时按需加载生效。

[!N