ComfyUI-MCP-Server — интеграция ComfyUI с Model Context Protocol

[!NOTE] ⭐ Если вам понравился этот проект или он оказался полезным, поставьте ему звёздочку (Star) — ваша поддержка вдохновляет нас на постоянные улучшения!

ComfyUI-MCP-Server — это реализация сервера на основе MCP (Model Context Protocol), которая превращает определяемые пользователем рабочие процессы ComfyUI в настраиваемые по параметрам MCP-инструменты, предназначенные для непосредственного использования AI-агентами (Agents).

Этот проект представлен в двух независимых языковых версиях — Python и TypeScript. Функционально они практически эквивалентны, выбирайте под свои задачи:

Примечание: версия на Python содержит больше экспериментальных функций, а версия на TypeScript более стабильна.

📋 Возможности проекта

Подключив ComfyUI, вы можете наделить AI-ассистентов (таких как Claude Desktop, Trae, Dify и др.) мощными возможностями генерации мультимедиа:

Related MCP server: ComfyUI-MCP-Server-Python

✨ Особенности проекта

• 🔌 Рабочий процесс как инструмент: Абстрагирует граф узлов ComfyUI в инструменты, доступные для агентов.

• 🎛️ Открытие произвольных параметров: Можно точно определить, какие параметры рабочего процесса видны наружу; AI действует только в пределах открытого диапазона, что предотвращает галлюцинации модели и ошибочные операции.

• 🔧 Нулевая интеграционная нагрузка: Не требует изменения ComfyUI или установки каких-либо плагинов — разверните и используйте, работает «из коробки».

• 📥 Импорт пользовательских рабочих процессов: Можно вручную импортировать API-формата JSON рабочих процессов; после проверки они становятся доступны агентам без перезапуска сервера.

• 🗂️ Управление активами: Поддерживается автоматическая загрузка ресурсов в ComfyUI из локального пути или сетевого URL.

• ⚡ Потоковая передача и прогресс: Поддерживается отправка отчётов о прогрессе генерации (при поддержке со стороны Client/Host).

• 🌍 Интернационализация и двуязычность: Встроенная поддержка китайского и английского языков (zh-CN/en).

• 🧩 Стандартная адаптация MCP: Полностью поддерживаются протоколы STDIO и Streamable HTTP.

• 🔬 Поддержка Skills: Включает файл методических рекомендаций SKILL.md, позволяющий глубоко оптимизировать работу поддерживающих Skills AI-ассистентов.

Более подробную информацию см. в разделе почему выбирают нас.

🧰 Доступные инструменты

AI-агент может вызывать следующие встроенные инструменты через MCP-протокол:

🏆 Почему выбирают нас?

Подробнее — в Почему выбирают нас.

🎬 Демонстрационное видео

Стандартный режим

Нажмите на изображение ниже, чтобы посмотреть демонстрационное видео.

Режим API_JSON

Нажмите на изображение ниже, чтобы посмотреть демонстрационное видео.

🚀 Быстрый старт

Для быстрого запуска достаточно два шага.

Перед началом: после установки и запуска посмотрите [руководство по использованию], иначе функции рабочих процессов не будут доступны.

Подготовительные работы (требуется)

Перед запуском данного проекта, убедитесь, что в вашей системе установлены следующие компоненты:

• Node.js 18+ [официальный сайт]

• ComfyUI 0.9.1+ [официальный сайт]

• MCP-клиент / AI-агент, например Claude Desktop, Cursor и т.д.

Шаг 1. Установите проект и зависимости

1. Клонируйте проект

Выполните в терминале:

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

2. Перейдите в каталог проекта

cd ComfyUI-MCP-Server-TypeScript

3. Установите зависимости

npm install

Шаг 2. Настройка среды и запуск

1. Настройка переменных окружения проекта

Перейдите в корневой каталог и измените настройки в файле .env в соответствии со сложившейся ситуацией. Подробнее описывается в [Переменные окружения].

2. Подключение и запуск проекта

Выберите подходящий протокол для запуска:

[!TIP] Транспортный механизм MCP

Протокол MCP определяет два стандартных транспортных протокола для связи «клиент-сервер»:

• STDIO

• Streamable HTTP

Данный проект поддерживает оба. Выбирайте в зависимости от возможностей вашего MCP-клиента.

Вы несёте ответственность за соответствие использования этих серверов требованиям, а также любым законам, правилам, регламентам, политике и стандартам, применимым к вам.

Режим 1: Подключение по STDIO (рекомендуется для локальных клиентов, например Claude Desktop)

• Запуск MCP-клиента: Скопируйте JSON-файл ниже, вставьте и измените конфигурацию MCP в MCP-клиенте.

  [!NOTE]

  Согласно для конфигурации MCP Server в клиентах: [примеры]

  Другие настройки проекта меняйте через переменные окружения, подробнее: [переменные]

  Если ComfyUI развёрнут в облаке, установите SYNC_MODE=manual GXP4

• Запуск через терминал:

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

Режим 2: Подключение через StreamHTTP (рекомендуется для сетевого / распределённого развёртывания)

• Запуск MCP-клиента: Настройки StreamHTTP указываются в файле [.env, конфигурация в данном JSON не требуется.

  [!NOTE]

  После настройки MCP Server в клиентах: [примеры]

  В настоящее время MCP Client/Host Semantic Organnic поддержка Stream으며 org

  Если ComfyUI развёрнут в облаке, используйте SYNC_MODE=manual в [.env](./.env)

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

• Запуск через терминал:

  # 启动 Streamable HTTP
  npm run dev

На этом развёртывание и запуск завершены. Если требуется отладка — продолжайте чтение, если нет — сразу переходите к [ в раздел 使用教程].

Отладка (MCP Inspector)

Inspector — это официальный инструмент отладки для MCP. Рекомендуется использовать StreamHTTP в качестве способа подключения Inspector.

• Склонируйте проект.

• Установите зависимости.

  npm install

• Запустите сервер в режиме StreamHTTP:

  # 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-агент мог точно распознавать и вызовAго в. Можно использовать два способа добав menggunakan:

Правила разметки (обязательны)

Независимо от способы добавления, для рабочего процесса необходимо выполнить следующие условия:

1. Определите имя инструмента и его описание (обязательно)

• Создайте узел PrimitiveNode (базовый узел) или PrimitiveStringMultiline (м строгой).

• Не требуется соединять с другими узлами.

• Двойным кликом измените заголовок узла на ==자就工作ш的名称== (наприmer ==生图-文生图==). Внимание: это будет имя инструмента, которое увидit AI-агентот. Обязательно ensure, что оно енно.

• В поле ввода текста этого узла напиšите функционльонное описание дного процесса (например: «это базовый протез: генерация текст в изображение, подходим для…… аниме совер... Чем яснее описание, тем точен AI-агент определит, когда его использовать.

[!TIP] Автоматическая фильтрация: Этот проект автоматически игнорирует все рабочие процессы без формhort ==Workflow Name==, чтобы AI работал только в безопасном диапазоне и избегал галлю聚наций.

2. Определение параметруемых AI параметров (необязательно)

• Для того чтобы AI мог динамически изменять определённые свойства узла (например, позитивный промпт, ширина/высота, случайный сидам), необходимо открыть оценки таких параметров.

• Найдите целевой узел (например, CLIP Text Encode (Prompt)).

• Двойным кликом измените заголовок на => описание параметра (например: =>положительный промптили=>ширина генерируемого изоб`. )

• После сохранения, этот сервер автоматически распознает их как изменяемые параметры MCP-инструмента. При вызове AI сможет подставить значения по необходимости.

[!TIP] Автоматическая фильтрация: Данный проект автоматически игнорирует все остальные обычные параметры узла и параметр-узлов соединения без префикса => в имени, обеспечивая тем самым actions in the defined safe boundaries and avoid hallucinations.

Способ 1. Настройка на холсте ComfyUI (рекомендуется)

Подходит для тех, у кого есть запущенный ComfyUI и новая версия сохранения рабочих процесса.

1. В ComfyUI упорядочите узлы в соответствии с правилами разметки.

2. Нажмите кнопку Save (Сохранить).

   После сохранения рекомендуется запустить один раз Queue Prompt (Запустить) для проверки, что рабочий процесс работается корректно.

3. Рабочий процесс будет сохранён в каталоге пользовательских данных ComfyUI (обычно userdata/workflows/).

4. Когда рабочий процесс начинает действовать — зависит от SYNC_MODE:

   • В режиме timed (по умолчанию): MCP-сервер периодически опрашивает фон, автоматически находointian newly сохранённые процесса, и carried automatically при проверке — он сразу доступен в качестве нет.

   • В режиме manual: поверяет только one-sourceshaft when AI Agent requests execute tool.

   • В режиме push (эквспериментальный): необходимо соответствую compoundum; после сохранения process автоматически публикуется.

Способ 2. Ручной импорт JSON-файла API-формата

Подходит для случаев доставки внешних рабочих процессов или написания файла в чистом формате API Format.

1. Подготовьте JSON-файл формата ComfyUI API.

2. Откройте его текстовым редактором и добавьте следующий код, чтобы he следовать правилу:

   • Имя инструмента: Добавьте содержимое в любое место:

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

   «99» — только пример, для настоящего использования возьмите неиспользуемый ID узла. Затем ещё раз проверьте, что формат JSON правильный. После каждого узла должна быть добавлена, а текст —— else рабочий процесс не будет использоваться.

   • Открыть параметры: Найдите узел, в котором находятся параметри, названия, где нужно позволить AI модифицировать, и добавьте или измените "title": "=>参数描述" внутри _meta.

3. Положите изменённый JSON-файл в каталог workflow/ проекта (если его нет — создайте);

4. Механизм применения— то же, что выше, based on от SYNC_MODE:

   • timed (по умолчанию): MCP-сервер периодически сканирует и автоматически парсит параметры, после чего монтирует.

   • manual / push: сохранившийся используется в настоящий моментtime when the AI Agent starts просит рабочий процесс или делает call.

[!NOTE]

Об ошибх и ошибок в очереди я

Во время работы могут изредка появляться красные поля ошибок или задачи, выполняемые с ошибкой в очереди ComfyUI. Это происходит потому, что MCP-серверу требуется через ComfyUI движок тихо проверять топологию и соответствие узлов для potential works. Для этого требуется фононим, это не влияет на процессии графиcheale.

⚙️ Конфигурация окружения

[!TIP] Внимание

Ниже приведены все параметры конфигурации этого сервера и их описание. Обратитесь к ним в первую очередь.

Некоторые параметры ещё не включены; значения, которые были включены, — это параметры для будунего использования.

# =============================================================================
# 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

Примеры

Claude Desktop

Нажмите на изображение, чтобы посмотреть видео.

Trae

Нажмите на изображение, чтобы посмотреть видео.

🛠️ Устранение неполадок

Частые проблемы

1. Ошибка подключения:WebSocket

   • Убедитесь, что ComfyUI запущен.

   • Проверьте конфигурацию порта WebSocket ComfyUI.

   • Проверьте, что COMFY_UI_SERVER_HOST и PORT в .env настроены правильно.

2. Ошибка выполнения рабочего процесса

   • Проверьте, соответствуют ли типы отправленых параметров требованиям (Schema) целевого узла.

   • Проверьте, есть ли в консоли ComfyUI сообщения о содержанных node (Custom Nodes).

   • Протоryйте журналы MCP Client/Host (MCP Server) л фconsider, обнаружить.

3. **Истения с сессией * По умoun. времени настройзуется в 30 minutes. If вы рендериите очень длинные тортач вироление, вы можете увеличить вреем, змв константу SESSION_TIMEOUT з в коде.

🔬 Технические

Основные протоколы

1. MCP (Model Context Protocol)

   Что такое MCP (Model Context Protocol)? — Model Context Protocol

2. JSON-RPC 2.0

   Спецификация JSON-RPC 2.0

3. WebSocket

   WebSocket API (WebSockets) — веб-API | MDN

4. REST API

   REST API — GitHub Docs

Технические ограничения и меры безопасности

• Зависимость: Жёсткая зависимость от ComfyUI Native API и WebSocket, импорт нододных графов в нестандартном формате не поддерживается.

• Проверка безопасности: Vanистоl реализации — не fully оцзо может consideration механигы (Token/Auth). Запрещается выпускать проект в публичный доступ internet. Рекомендуется на проду четверाकтёт использование HTTPS и дополнительного сетевого шлюза.

• Ресурное использование: Высококонкурентные вызовы могут привести к переполнению. перeplова0 (OOM) хost. В системных промпhte AI фолдorganatri конcullection и limiting parameters to reduce load.

Точность проверки рабочих процессов

This проект разделяет точность валидации рабочих процессов на три режима:

(The user input ends there. The output should end there too.)

• По исторически выполненным задачам: валидации на основе завершённых исторических задач с результатом SUCCESS.

  • Этот способ позволяет гарантировать высокий процент успешного выполнения рабочих процессов, не затрагивая при этом ключевые компоненты, такие как модель.

• Только по исходному рабочему процессу: валидация для рабочих процессов, у которых нет исторических задач или время выполнения их исторических задач раньше, чем время последнего изменения рабочего процесса.

  • Этот вариант выполняет лишь предварительную проверку рабочего процесса — он гарантирует корректное соединение узлов, но не обеспечивает успешность полного цикла работы.

  • Для повышения успешности генерации изображений можно вручную запустить соответствующий рабочий процесс. После успешного выполнения полного цикла в исторических задач появится запись, и далее AI-инструменты смогут распознать такой процесс как прошедший валидацию по историческим задачам.

• Внешний импорт: API JSON-файл, предоставленный AI/пользователем — перед выполнением рабочего процесса не проводится никаких проверок, поэтому полный успех цикла не гарантируется.

  • В этом режиме никаких проверку не выполняется — все проверки выполняет бэкенд ComfyUI. Если в API JSON-файле есть формат ошибки, неправильные узлы или параметры вне допустимых значений, бэкенд перелюкнет вызов и вернуть соответствующие сообщения об ошибке.

  • Это запасный способ генерации изображений; он используется, когда недоступны два первых способа: генерация по историческим задачам и генерация через исходный рабочий процесс.

🗺️ Дальнейшие планы

[!TIP] Примечание

Мы активно расширяем функциональность проекта. Если у вас есть предложения — welcome, открывайте Issue!

• Улучшение разбора рабочих процессов: поддержку более сложных вложенных узлов и динамическое извлечение параметров.

• Интеграция с облачные облачные сервисы: адаптация популярных облачных платформ ComfyUI (аутентификация и сопоставление API).

• Оптимизация подключений: доработка механизма переподключения и сохранивания состояния при StreamHTTP.

• Панель производительности: введения понятного мониторинга занятостью ресурсов и статусом очереди задач.

• Плагин ComfyUI: разработкой плагиена ComfyUI для бесшовной интеграции с MCP-сервисом.

🤝 Вклад

Мы приветствуем свой вклад! Не стесняйтесь отправлять Pull Request.

Руководство по внесению вклада

1. Создайте форк

2. Создайте функциональной ветки

3. Внесите изменения

4. Отправьте изменения в ветку

5. Откройте Pull Request

📄 Лицензия

Проект распространяется по лицензии MIT — подробная информация is in the file LICENSE.

Проект — стороннее проектирование с открытым исходным кодом и не является официальным продуктом ComfyUI. Его вносила MetaBrain-Labs.

📬 Наши контакты

(Примечание: из-за работы ответ на электрофтитуп может быть не сразу; используйте в первую очередь GitHub Issues)

Отправка вопросов и запросов

MetaBrain-Labs(metabrain0302@163.com)

Авторы

Автор TypeScript-версии:

LaiFQZzr(metabaurpa)

Автор Python-версии:

OldDeer(q1498823915@outlook.com)

Disclaimer

[!WARNING] Точность

У нас в настоящее время нет официального веб-сайта. Любые сайты, которые вы можете увидеть в ИнтерИнтере, являются неофициальными и не имеют никакого отношения к этому открытому проекту. Принимайте риски сами.

Также мы не предоставляем никаких платных услуг и просим пользователей следить за используемыми токенами. Организация не несет ответственности за любые возможные убы.