ComfyUI-MCP-Server - Integración del Protocolo de Contexto de Modelo de ComfyUI

![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg ![Ask DeepWiki](https://deepwiki.com/badge.svg

[!NOTE] ⭐ Si te gusta este proyecto o lo encuentr útil, da le un clic en "Star", tu apoyo es nuestro motor del constinuar nojoando.

ComfyUI-MCP-Server es una implantación de servidor basada en el MCP (Model Context Protocol / Protocolo de Contexto de Modelo); convierte los flujos de trabajo que permite del usuario en ComfyUI en herramientas MCP con parámetros configurables, para que los agentes de IA (Agents) los utlinen directamente.

Este proyecto is provided with two versions of language Pytthón and TypScript, with equivalent functionality básic.* They are available for your need:

Note: the Python version has more experimental features, so the type then is more stable.

📋 Funciones del proyecto

Through a project, you can connect to ComfyUI and confer to an AI assistant (like Claude Desktop, Trae, Dify, etc.) a powerful multimedia generation capacity:

Related MCP server: ComfyUI-MCP-Server-Python

✦ Proyecto features

• 🔌 Flujo de trabajo como herramienta: convert the node graph of ComfyUI into tools available for agents.

• 🎛️ Exhibición de parameters custom: defines precisely in the flow which parameters are visible externally, and limits the IA to operate only in the exposed space, thus preventing the model against hallucinations and errors.

• 🔧 Integración none invasive: no need to modify ComfyUI itself, no install any plugin; it is ready once connecting, out-of-the-box.

• 📥 Importación personalizado de flujos: can import API‑formatted flow JSON manually, to be available to the agent after validation, without restarting the server.

• 📂 Gestión de activos: allows upload resources to ComfyUI automatically, by local path or URL.

• ⚡ Stream & progreso: it supports progress reports (if Client/Host supports it).

• 🌍 Internacionalización bilingual: includes the internationalization zh-CN/en.

• 🧮 Standard MCP adapter: full support for STDIO and Streamable HTTP transport protocol.

• 🔬 Support de Skills includes SKILL.md, for AI assistants that support Skills, and performs deep optimization by means of these skills.

More see why to choose

🧰 Conjunto de herramientas available

IA agents can invoke the following integrated tools through model context protocol:

| Table: Herramienta | herramienta name | Description |

| get_core_manual | Get project hub manual | [System guide] principal hub and dictionary of operation.**** | | --In newspaper pulls. | | get_core_manu | Get project core manual | **System guide core protocols and operation dictionary. You should read it before initializing and calling the other tools. Get the latest fill parameter strategy and error recovery mechanism. | | get_workflows_catalog | Get works of flows catalog | [Catalog search] Get all of the currently supported flow list. Instructions involving the image generate must be exactly this list; never invent or guess flow names. | | get_workflow_API | Get details of a flow | [flow API] Reads the complete bottom-level JSON topology of the goal flow. Size huge; only call when you need to review the last layer sensations, and never use it in routine to keep the context clean. | | moun work_workflow | Mount flow | [Param mounting] Extracts the supported interactive parameter Schema (blocking the wiring details) for the target task. Must call it prior to submitting a flow task to get the allowed key names table. | | queue_prompt | Execute task of flow | [Task submit] Submit the Prompt to the queue. The bottom scheduler calculates and syncs the progress to the Host in real time. Make sure all keys are mount-validated; never make up key names. | | queue_custom_prom | Execute custom flow | [Advanced mode] Submit a full native ComfyUI API JSON directly to queue. Only avail in debugging/AI expert direct instructions and never in normal tasks. | | save_custom_workflow | Save customized flow | [Save flow] Save parameterized the server to flow directory, then automatic SDX validate and mount. If JSON doesn't contain at least one == имя == node that meets mount rules, save will be rejected. | | save_task_assets | Save generated assets | [Generated assets] Get execution history for prompt_id and download & save all generated media (images/video/GIF etc.) to selected local directory. | interrupt_prompt | Cancel task | For a specific prompt_id, cancel the computing process and remove waiting items from the queue by force. | | get_prompt_result text output & assets [ | Output capture & assets ] Gets the node snapshot after the Prompt is executed, extract generated target files (img/video urls) another get traceback for diagnose error. | get_system_status | Get system | [Monitor] gather memory, VRAM and top metrics to debug low-level failures such as OOM/ deadlocks. | list_models | Lists model file | [Models] poll local disk / models folder. Whenever your parameters involve a concrete model, first call to list and tune. Not invent model filename. | upload_assets | Imports to ComfyUI | [Upload file] Upload local file or URL to input directory of ComfyUI server to be applied immediately in flows.

🏆 Why choose us?

More details when you check Why choose us

🎬 Demo videos

Default method

Click below to watch demo video.

API_JSON method

Click below image for demo video.

Inicio requires go

Quickly start in two steps.

remind: after installing and startup, you still need, read [use guide; otherwise flow features are not work.

Preparing (Required)

Before this project start, confirm the following software installed in your system:

• Node acR 18+ [official link]*

• ComfyUI 0.9.1+ [official link]

• Client / Agent for MCP e.g. Claude, Cursor etc.

Step 1: Install project and deps

1. Clone this project In the terminal, do:

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

2. Move to the project directory

cd ComfyUI-MCP-Server-TypeScript

3. Install dependencies

npm install

Step 2: Configure your environment and start

1. Project env configuration

Make a directory to root, and change .env values as needed by your environment. Details config see: [Environment variables]

2. Connect and run

Select the transport method that suits you:

[!TIP]

MCP transport mechanism

MCP protocol defines standard ways between client-server communication:

• STDIO

• Streamable HTTP

This project method both; pick by your MCP client's ability.

You are responsible for own uses or to remain compliant with the legal terms, laws, rules/regulations/policies.

First: STDIO connection (Recommended - Claude Desktop, local) lang-: */

• Start from MCP client: Copy and paste, then edit the following JSON in the MCP client config:

[!Note]

Some clients need a check: examples: [examples]

Other project settings set in environment variables: see [Env var](#config)

When ComfyUI is cloud, set "SYNC_MODE" to "manual" GXP4

• Start from terminal:

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

Second: StreamHttp connection (recommended for network/distributed deployments. )

• From MCP client: StreamHTTP project settings are all in [.env, something not to in this JSON below.

[!Note]

How to configure MCP server in different client, see: [examples]

The set of StreamHTTP-compatible MCP Client/Host is currently small rules; choose by your requirement.

If *ComfyUI runs in the cloud, set "SYNODE" mode set in [.env] to "manual" GXP6

• Start from terminal:

# 启动 Streamable HTTP
npm run dev

The project is now deployed and started. Go to the next if you need tools, otherwise skip directly to [use guide.

MCP Inspector

Inspector Is the official MCP debugging tool, and it is recommended to use StreamHTTP as its transport.

• Clone the project

• Install dependencies (when needed)

npm install

• Start the server using StreamHTTP:

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

• Start the Inspector:

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

After startup, the console outputs a similar address; copy/paste the URL into the browser and debug:

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

After inspector has launched, Web page configuration reference:

Usage: start the workflow.

This is the project, you can add available workflows by simply marking in ComfyUI with specific markers, by an AI agent can find exactly:

Rules for markup (must know)

No matter how you add workflows, you must include the following marker node:

1. Define the tool name & shorthand description (MAND)

• Create new a PrimitiveNode (basen node) or a PrimitiveStringMultiline (multiline string node) — no need to connect it to any node.

• Double-click the title, set to ==you work name== example: (==生图-文生图==). Note: it is the name the AI agent will see; it must be unique.

• In the text area of the node, write the description of the flow's purpose (example: “This basic bottom-to-image flow is great for anime”). The more plain description, the better AI works decide when is right call.

[!TIP] auto filter: This project ignores any workflow missing ==Workflow Name== — AI model operation only happens in a defined range ; avoid hallucinations.

2. Expose optional parameters

• If you want AI to dynamically modify node attributes (e.g. prompt, width / </br style to a node`?); The return **

• Double-click node title and change to =>param description (e.g. =>positive prompt or =>generated width).

• After you save, server will automatically paint the param as an MCP variable, AI can fill it when call.

[!TIP] auto-Filter: The auto filter will ignore parameters of regular-flows without the => title pref. Therefore the AI only changes exposed.

Method 1: Set in ComfyUI canvas (recommended)

Suitable when running ComfyUI and new workflow saving works:

1. In ComfyUI organize the above mark node.

2. Click Save (Adobe) button. After Save, recommend to run once by click Queue Prompt and test.

3. The flow save to ComfyUI user data dir (typically userdata/workflows/).

4. When it works depends on SYNC\_MODE:

   • timed (defaults): background polling mounts it into tools automatically when validation passes.

   • manual: scans of new flow only when agent

   • push (experimental): need a ComfyUI plugin. Real-time push after.

Method 2: manually import an API flow JSON

Works for external flow, or use pure API format files:

1. Make ready your ComfyUI API JSON file.

2. Open it and add core markers:

   • Tool name: add anywhere:

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

“99” only is a example? Use an unused node ID in real. Add it and inspect check JSON with each node terminator commas. Note: a miss comma can break.

• Expose parameter: Locate the node containing the param to be changed, and add / alter _meta "title": "=>paramdescriptionChoose* etc. Use.

3. Put the JSON file under workflow/ directory (create it if absent).

4. **same way as above, relying on SYNC_MODE’**: *timed`: server will scan automatically, and mount parsed params.

   • manu/push: the flow will be available next request the agent needs.

[!NOTE]

About errors/fail queue During use, you can in ComfyUI queue see red/error tasks. That is normal — the MCP server checks the workflow and internal validations, and the rest is safe. It is a normal behavior, not affecting other tasks or AI, please be relaxed.

á Config.

[!TIP] Note

All server environment variables are described below. This priority is reading them. Some of the following are not yet activated but planned.

# =============================================================================
# ComfyUI MCP Server - Configuration
# 配置文件说明：
#   [User Config]   用户配置 —— 根据您的部署环境修改此区块
#   [System Config] 系统配置 —— 保持默认即可，无需修改
# =============================================================================

# =============================================================================
# [User Config] 用户配置
# Modify this section based on your deployment environment.
# 根据您的部署环境修改以下内容。
# =============================================================================

# Language for MCP tool descriptions.
# MCP 工具描述的显示语言。可选值：en（英文）| zh（中文）
LOCALE=en

# -----------------------------------------------------------------------------
# ComfyUI Server Connection / ComfyUI 服务器连接
# -----------------------------------------------------------------------------

# Full URL of your ComfyUI server. No trailing slash.
# ComfyUI 服务器的完整地址，末尾不加斜杠。
COMFY_UI_SERVER_IP="http://192.168.0.171:8188"

# Host (without protocol) and port. Used separately for WebSocket connections.
# 主机名（不含协议头）和端口号，WebSocket 连接时单独使用。
COMFY_UI_SERVER_HOST="192.168.0.171"
COMFY_UI_SERVER_PORT="8188"

# -----------------------------------------------------------------------------
# Sync Mode / 同步模式
# -----------------------------------------------------------------------------

# Controls how the server detects workflow updates from ComfyUI.
# 控制服务器检测 ComfyUI 工作流更新的方式。
#
#   timed  — Background loop polls ComfyUI at a fixed interval. (default)
#             后台循环以固定间隔轮询 ComfyUI。（默认）
#
#   push   — [Experiments] ComfyUI plugin sends real-time save events; long fallback poll as safety net.
#             Requires COMFY_UI_INSTALL_PATH (must be on same machine as ComfyUI).
#            [实验性功能] ComfyUI 插件实时推送保存事件；兜底长轮询作为安全网。
#             需要配置 COMFY_UI_INSTALL_PATH（需与 ComfyUI 同机部署）。
#
#   manual — No background loop. Refresh only when tools are called
#             (get_workflows_catalog / mount_workflow / queue_prompt).
#             无后台循环，仅在调用工具时按需刷新
#             （get_workflows_catalog / mount_workflow / queue_prompt）。
#
SYNC_MODE=timed

# Polling interval in seconds for timed mode.
# timed 模式的轮询间隔（秒）。
SYNC_POLL_INTERVAL_SECONDS=3

# Fallback polling interval in seconds for push mode (safety net for missed events).
# push 模式的兜底轮询间隔（秒），用于捕捉遗漏的推送事件。
SYNC_EVENT_FALLBACK_INTERVAL_SECONDS=300

# Cooldown in seconds between manual mode refreshes.
# Prevents excessive ComfyUI API calls when tools are called in quick succession.
# manual 模式两次刷新之间的冷却时间（秒），防止工具短时间内连续调用时频繁请求 ComfyUI API。
ONDEMAND_REFRESH_COOLDOWN_SECONDS=30

# -----------------------------------------------------------------------------
# Push Mode Plugin / 推送模式插件（仅 SYNC_MODE=push 时需要）
# -----------------------------------------------------------------------------

# Absolute path to your LOCAL ComfyUI installation root directory.
# Required when SYNC_MODE=push: MCP Server will automatically deploy a lightweight
# backend plugin that pushes workflow save events in real-time.
# Leave blank if ComfyUI runs on a remote machine or if using timed/manual mode.
#
# 本地 ComfyUI 安装目录的绝对路径。
# 使用 SYNC_MODE=push 时必填：MCP Server 会自动部署一个超轻量推送插件，
# 实现工作流保存后的实时推送通知。
# 若 ComfyUI 部署在远端机器上，或使用 timed/manual 模式，请留空。
#
# Windows 示例 / Example: COMFY_UI_INSTALL_PATH=C:/ComfyUI
# Linux   示例 / Example: COMFY_UI_INSTALL_PATH=/home/user/ComfyUI
COMFY_UI_INSTALL_PATH=

# -----------------------------------------------------------------------------
# Workflow Marker Patterns / 工作流标识符正则表达式
# -----------------------------------------------------------------------------

# Regex identifying the workflow name node (title of a PrimitiveStringMultiline node).
# Must contain ONE capture group that extracts the MCP tool name.
# Default matches titles like "==my_workflow=="
# 工作流名称节点的标识正则（PrimitiveStringMultiline 节点的 title）。
# 必须含一个捕获组提取工具名，默认匹配 ==名称== 格式。
WORKFLOW_NAME_REGEX=^==(.+?)==$

# Regex identifying configurable parameter nodes.
# Must contain ONE capture group that extracts the parameter description.
# Default matches titles like "=>prompt text"
# 参数节点的标识正则，必须含一个捕获组提取参数描述，默认匹配 =>描述 格式。
WORKFLOW_PARAM_REGEX=^=>(.+)$

# =============================================================================
# [System Config] 系统配置
# Internal settings — change only if you know what you are doing.
# 内部运行参数，通常无需修改。
# =============================================================================

# -----------------------------------------------------------------------------
# MCP Server / MCP 服务地址
# -----------------------------------------------------------------------------

# MCP server bind address and listening port.
# MCP 服务器的监听地址和端口（MCP 客户端连接此处）。
MCP_SERVER_URL="http://192.168.0.192:8189/mcp"
MCP_SERVER_IP="192.168.0.192"
MCP_SERVER_PORT="8189"

# -----------------------------------------------------------------------------
# Logging / 日志配置
# -----------------------------------------------------------------------------

# Minimum log level written to stderr.
# 输出到 stderr 的最低日志级别。
# DEBUG | INFO | WARNING | ERROR  (default: INFO)
LOG_LEVEL=INFO

# Optional absolute path for a log file.
# When set, logs are written to BOTH stderr and this file.
# Leave blank to disable file logging.
# 可选：日志文件的绝对路径。填写后同时输出到 stderr 和文件。留空则不开启文件日志。
# LOG_FILE=

# Log file rotation size. Default: 10 MB
# 日志文件切割大小，默认 10 MB。
# LOG_ROTATE=10 MB

# Number of rotated log files to retain. Default: 7
# 保留历史日志文件个数，默认 7。
# LOG_RETAIN=7

Examples

Cluade Desktop

Click image to demo.

Trae

Click image to see demo.

△ Troubleshooting

FAQ

1. websocket error

   • Ensure ComfyUI running then

   • Check ComfyUI websocket port config

   • Check .env COMFY_UI_SERVER_HOST and PORT.

2. work flows failed * verify that parameter schema matches the target.

   • See Comfy console Custom Nodes.

   • See CorreMCP Client/Host logs for details.

3. expired session

   • default HTTP session=30m. long-generation: edit source SESSION_TIMEOUT constant.

这 🔬 Teh detail

Core protocol

1. MCP (Model Context Protocol): What is the Model Context Protocol (MCP)? - Model/Context Protocol

2. Immediately JSON-RPC 2.0

3. WebA **Socket

4. Rest Api

Tech limits .

• Dependency: depen on original ComfyUI API and Webocket; Does not support non standard import.

• Security: current version no authentication, do not expose to public. Need an HTTPS / gateway when in production.

• Resources: high workload can cause OOM (memory / VRAM). Limit required request concurrency in your system prompt.

Workflow validation accuracy

The project divides this into three types:

Workflow validation.

• 通过历史任务：根据已执行完毕且执行结果为SUCCESS的历史任务校验。

  • 该方式在模型的等核心不受影响的情况下进行校验，通过对任务结果的校验来保证工作流执行成功率。

• 仅通过初始工作流：根据无历史任务或历史任务其执行时间早于对应工作流最新修改时间的工作流进行校验。

  • 该方法仅对工作流进行初步校验——确保节点间连接无异常，但不保证工作流完整运行成功。

  • 为保证图片生成成功率，可考虑手动运行相关的工作流。在工作流的完整流程运行成功后，历史任务中会出现对应的任务记录，后续的AI工具即可识别出该工作流已通过历史任务校验。

• 外部导入：AI/用户自行提供的 API JSON 文件。在 workflow 执行前，不做任何校验，因此不保证 workflow 完整流程成功。

  • 该方法不做任何校验，全部校验由 ComfyUI backend 进行。如果 API JSON 文件格式、节点或参数范围有问题，ComfyUI后端会拦截并返回相应错误信息。

  • 该方法是兜底生成图片的方法，在以上历史任务生成图片、初始工作流生成图片都不可用的情况下使用。