env сервера в
~/.claude/settings.json) или флагами CLI. Приоритет цели ComfyUI:
--comfyui-url / COMFYUI_URL → COMFYUI_HOST/COMFYUI_PORT → автоопределение.
Режимы развёртывания
comfyui-mcp работает в одном из трёх режимов, автоматически выбранном из
окружения:
Инструменты, которым нужна локальная установка (
restart_comfyui с action: "start" / apply_manifest / list_local_models (action:"remove") / get_image (action:"list_outputs") / и т. д.)
возвращают понятную ошибку в удалённом или облачном режиме. В удалённом и облачном режимах сервер пропускает
локальное автоопределение COMFYUI_PATH, чтобы устаревшая локальная установка не могла незаметно поглотить загрузки или скачивания моделей,
которые агент предназначает настоящей цели — задайте COMFYUI_PATH явно, если хотите
смешивать.
Подключение
Полный URL экземпляра ComfyUI, например
https://my-comfy.example.com. Эквивалент
флага CLI --comfyui-url. Имеет приоритет над хостом/портом и пропускает автоопределение порта.
Префикс пути сохраняется (например, https://host/comfyapi), чтобы экземпляры за reverse-прокси
маршрутизировались правильно. Когда хост не петлевой (всё кроме 127.0.0.1 / localhost /
::1 / 0.0.0.0), сервер входит в удалённый режим и пропускает автоопределение COMFYUI_PATH.Абсолютный путь к локальной установке ComfyUI. Автоопределяется по обычным местам, если не задан
(подавляется в удалённом/облачном режимах). Нужен инструментам только для локального режима (установка/управление узлами, удаление
моделей, чтение логов, список выходных файлов).
Необязательный корень checkout кода для раздельных установок, где
main.py и
.venv находятся отдельно от данных и моделей. Pip, venv и обновление ядра
используют этот путь. Чтение/запись пакетов (custom_nodes) остаётся на
--base-directory / COMFYUI_PATH. В удалённом режиме путь игнорируется.Shell-команда, перезапускающая внешне управляемый ComfyUI — например,
docker restart comfyui или systemctl --user restart comfyui. Если задана,
restart_comfyui выполняет эту команду вместо kill+relaunch (который требует,
чтобы путь запуска установки разрешался — невозможно для контейнера или
лаунчера, чей main.py заякорен только внутри собственного namespace), и
panel_restart_comfyui тоже идёт через неё. Только локальные цели; удалённые
и облачные цели сохраняют путь перезагрузки через Manager. Перезапуск
проверяет, что экземпляр вернулся исправным, и сообщает цикл как
подтверждённый, только когда down→up был реально наблюдён.Удалённо за reverse-прокси / API-шлюзом
Для самостоятельно хостящегося ComfyUI, выставленного под префиксом пути и/или своим слоем аутентификации (маршрут nginx, API-шлюз, край SSO) — это не Comfy Cloud:COMFYUI_URLсохраняет префикс пути (например,https://host/comfyapi), так что запросы идут под ним, а не бьют в/prompt,/system_stats, … в корне.- Переменные
COMFYUI_AUTH_*вешают общий заголовок аутентификации на каждый запрос ComfyUI (прямые HTTP-вызовы и нижележащая библиотека клиента/WebSocket). Это независимо от облачного режима, так что экземпляр с аутентификацией шлюза никогда не читается как Comfy Cloud.
Токен аутентификации для самостоятельно хостящегося ComfyUI за шлюзом. Когда задан, отправляется на каждый запрос
ComfyUI. Никогда не логируется.
Префикс схемы на значении токена, например
Bearer, Token.Client ID сервисного токена Cloudflare Access. Задавайте вместе с
CF_ACCESS_CLIENT_SECRET, чтобы достучаться до ComfyUI за Cloudflare Access — оба
отправляются (как CF-Access-Client-Id / CF-Access-Client-Secret) на каждый
запрос ComfyUI (HTTP и WebSocket наблюдателя очереди), так что коннектор проходит
шлюз Access вместо интерактивной страницы входа. Аддитивно к
COMFYUI_AUTH_TOKEN; оба действуют, если заданы оба. Никогда не логируется.Client Secret сервисного токена Cloudflare Access (пара к
CF_ACCESS_CLIENT_ID).
Отправляется, только когда заданы оба — наполовину настроенный токен игнорируется. Никогда не логируется.Comfy Cloud
ЗаданиеCOMFYUI_API_KEY переключает сервер в облачный режим: все HTTP-примитивы
(постановка в очередь, история, системная статистика, очередь, просмотр, загрузка) идут на cloud.comfy.org по HTTPS с
аутентификацией X-API-Key; инструменты WebSocket и локальной ФС/процесса выбрасывают понятную ошибку CLOUD_UNSUPPORTED.
Архитектура и диспетчер cloud-client изначально предложены
@picoSols.
Comfy-Org поставляет официальный агентский инструментарий — Comfy Cloud MCP (публичная бета) и Comfy In-App Agent (закрытая альфа), оба поддерживает команда Comfy и оба работают на Comfy Cloud. Если вы целитесь только в Comfy Cloud, это, вероятно, правильный выбор; см. Локально vs. Comfy Cloud. Облачный режим
comfyui-mcp ниже лучше всего, когда вам нужен один MCP на локальный / удалённый / облако или он нужен уже сегодня (он MIT и выпускается сейчас).API-ключ Comfy Cloud. Когда задан, сервер входит в облачный режим и говорит с настроенным облачным
URL вместо локального ComfyUI. Никогда не логируется.
Переопределить эндпоинт Comfy Cloud (в основном для тестов / staging).
Токены
API-токен CivitAI. Используется для gated/early-access скачиваний. Отправляется как bearer-заголовок (никогда в URL).
Зеркальный эндпоинт HuggingFace для регионов с ограниченной сетью (например,
https://hf-mirror.com). Все URL API и скачивания huggingface.co
переписываются на этот хост; ваш HUGGINGFACE_TOKEN по-прежнему едет для gated
репозиториев. Фактический стандарт — ту же переменную чтит huggingface_hub.Задайте
0, чтобы полностью отключить доступ к Civitai (регионы, где civitai.com
недоступен). Инициированные пользователем инструменты Civitai быстро падают с понятным сообщением «disabled
by config» вместо зависания; фоновые поиски provenance
тихо no-op.Токен GitHub, которым пользуются генерация скиллов и запросы метаданных узлов, чтобы избежать лимитов.
API-ключ comfy.org, пересылаемый размещённым API-узлам через полезную нагрузку
/prompt extra_data.
Если переменная окружения не задана, ключ читается из ~/.comfy-api-key (обрезанное содержимое файла;
рекомендуется chmod 600) — удобно для headless-установок, которые держат секреты
вне окружения/списков процессов.API-ключ Comfy Registry, которым пользуется
node_pack (action: "publish") для публикации пакета узлов. Передаётся comfy-cli через env, никогда не кладётся в args или логи.Поведение
Каталог, в котором ищутся воркфлоу
*.json. Каждый становится автозагружаемым инструментом запуска.Скачивание моделей
Кэш скачиваний моделей, адресуемый по содержимому. Повторные или параллельные скачивания одного URL переиспользуют кэшированный файл; целевой путь модели материализуется через hardlink (с откатом на копирование).
Максимальный размер кэша скачиваний в ГБ.
0 отключает вытеснение; сверх лимита наименее недавно использованные кэшированные файлы удаляются после завершения скачивания.Число параллельных соединений на одну загрузку модели. Одно соединение ограничено временем кругового обхода, а на многих CDN для моделей — ещё и лимитом скорости на соединение; параллельная загрузка байтовых диапазонов снимает оба ограничения.
1 отключает механизм и загружает в одно соединение. Применяется, только если хост объявляет поддержку байтовых диапазонов и подтверждает её пробным запросом, — иначе загрузка идёт в одно соединение ровно как раньше.Минимальный размер файла в МБ, который имеет смысл делить между несколькими соединениями. Ниже этого порога дополнительные обращения обходятся дороже выигрыша от параллелизма.
Надзор за процессом (локальные установки)
Применяется кrestart_comfyui (действия start и restart), когда comfyui-mcp управляет локальным процессом ComfyUI.
Максимум проб готовности, прежде чем сообщить, что старт не подтверждён. При
интервале по умолчанию 1 с это бюджет ~60 с. Его подняли с 20, потому что ComfyUI
с обычным набором кастомных узлов регулярно отвечает дольше 20 с на
/system_stats при холодном старте, и более короткий бюджет сообщал о старте как
неподтверждённом за мгновения до того, как здоровый экземпляр становился готов.Исчерпание бюджета значит, что старт ещё не подтверждён — не что он провалился.Когда включено, процесс ComfyUI, который неожиданно вышел, автоматически перезапускается. Намеренный
restart_comfyui с action: "stop" никогда не перезапускается.Максимум автоперезапусков, разрешённых в окне перезапуска, прежде чем сдаться.
Оркестратор панели и мост
Боковую панель comfyui-mcp-panel ведёт оркестратор панели — фоновый процесс, которому принадлежит петлевой WebSocket-мост и который запускает автономную сессию Claude Agent SDK на каждую вкладку панели на вашей подписке Claude (без API-ключей). Пакет панели сам стартует его при загрузке ComfyUI, так что обычно руками ничего запускать не нужно — см. Боковая панель. Чтобы запустить самим:Запустить оркестратор панели вместо MCP-сервера (то же, что
--panel-orchestrator).Петлевой порт WebSocket-моста панели, которым владеет оркестратор панели
(по умолчанию 9199).
Порог зависания рендера (секунды) для сторожевого таймера очереди/рендера оркестратора: текущее
задание, чей узел/прогресс не продвигался так долго, помечается как зависшее,
и однострочная заметка STALL/BACKLOG предваряет следующую реплику агента. Шаги видео
закономерно медленные, поэтому значение по умолчанию высокое. Ограничено 15–3600 с. Настройка панели
«Предупреждение о зависшем рендере (секунды)» (Настройки → Comfy MCP Agent → Общие)
переопределяет это вживую через кадр моста
set_config — переподключение не нужно —
и имеет приоритет над этим значением env.Защищённый мост (управление удалённым/облачным подом)
Когдаconnect <url> целится в удалённый https ComfyUI (например, под RunPod),
HTTPS-страница панели пода не может открыть обычный сокет ws://127.0.0.1 к мосту на
вашей машине — браузеры это блокируют (mixed content / Private Network Access).
Оркестратор автоматически повышает до защищённого туннеля wss://, так что это работает без
приглашения, в любом браузере. См. Развёртывание в облаке для полного
прохода и Собственный релей для своей
туннельной инфраструктуры вместо быстрого туннеля cloudflared по умолчанию.
Принудительно использовать обычный петлевой мост
ws:// даже при управлении удалённой https
целью, вместо автоповышения до защищённого туннеля. Используйте, если достукиваетесь до
пода через свой SSH port-forward (так что его страница уже петлевой
origin) и не хотите зависимости от Cloudflare. То же, что --insecure-bridge.Какой бэкенд защищённого моста использовать для удалённой цели:
cloudflared (по умолчанию
— эфемерный быстрый туннель, нулевая настройка) или relay (набрать
собственный релей, которым вы управляете, ради стабильного домена и без
сторонней зависимости быстрого туннеля). Действует, только когда активен защищённый режим
(удалённая https-цель, не COMFYUI_MCP_INSECURE_BRIDGE).Необязательный общий секрет, гейтящий, кто вообще может открыть сессию на вашем реле
(
?key=), независимо от токена моста на сессию. Имеет смысл только в режиме релея
и только если развёртывание релея задаёт RELAY_ACCESS_KEY.Наблюдение за заданиями
Уведомления о завершении поставленных в очередь заданий отслеживает наблюдатель (WebSocket, где доступен, иначе HTTP-опрос).Максимум секунд, которые наблюдатель ждёт завершения задания, прежде чем сдаться. Поднимите
для очень длинных видеорендеров или тяжёлых многостадийных воркфлоу. (Само задание продолжает
работать в ComfyUI — бросается только уведомление о завершении.)
Окно соблюдения отмены (секунды) для
queue (action:“cancel”): сколько ждать, пока
прерывание
реально остановит текущее задание, прежде чем эскалировать (к /free, затем сообщить, что рендер
WEDGED). ComfyUI проверяет флаг прерывания только между узлами/шагами, поэтому многоминутный
одиночный шаг не уважит его сразу — это ожидание и обнаруживает настоящее заклинивание.Ограничение поверхности инструментов
Для размещённого развёртывания — общий Open WebUI, командный фронтенд — оператор это не тот, кто пишет промпты. Переменные preset/allow/deny инструментов удерживают инструменты от модели целиком: удержанный инструмент никогда не регистрируется, поэтому его нет вtools/list, нет
в call_tool, и модель никогда не узнаёт, что он существует. Список разрешённых действий — более
узкий спутник для инструмента, который должен оставаться видимым: инструмент остаётся зарегистрированным, но
неперечисленное действие отклоняется, прежде чем его обработчик запустится.
safe — всё, кроме инструментов, которые меняют машину или библиотеку моделей.
Установка, удаление и перезапуск удерживаются. Рендер по-прежнему работает, как и
то, что с ним идёт: постановка генераций в очередь, list_api_nodes (размещённые партнёрские
узлы, которые тратят ПЛАТНЫЕ кредиты) и report_issue (заводит публичный GitHub issue). Используйте
readonly, если пользователи общего фронтенда не должны уметь тратить или публиковать.
readonly — только осмотр: рендеры не ставятся, ничего не пишется, ничего не тратится.
Оба также удерживают всю поверхность panel_*, которая управляет живым общим холстом.Имена инструментов через запятую, которые удержать, например
restart_comfyui,download_model.
Замыкающая * совпадает с семейством: train_*. Применяется поверх любого пресета и поверх
списка разрешений.Список разрешений через запятую. Когда задан, поверхность — ровно эти инструменты: всё,
что не названо, удерживается, даже если никакое правило deny его не упоминает. Используйте, чтобы вернуть отдельные инструменты
поверх пресета:
COMFYUI_MCP_TOOL_PRESET=safe плюс
COMFYUI_MCP_TOOL_ALLOW=panel_graph_outline,panel_query_graph.Только точное имя возвращает инструмент поверх пресета. Глоб (list_*) сужает
поверхность как любая другая запись, но не может заново открыть то, что пресет закрыл — иначе
ALLOW=list_* снова допустил бы list_packs, чьё действие install_deps ставит и
запускает сторонний код, а ALLOW=* сделал бы каждый пресет бесполезным.Точные пары
tool:action через запятую. Когда задано, каждый вызов инструмента с полем
action должен совпасть с одной из этих пар; инструменты с действием, опущенные из
списка, не могут отправить никакое действие. Это ограничивает объединённые инструменты, чьи имена сами по себе
больше не выдают радиус поражения — например, разрешить осмотр очереди и точечную
отмену, не разрешая правки очереди или глобальную очистку:queue:list,queue:status,queue:cancel,enqueue_workflow:enqueueСочетайте с COMFYUI_MCP_TOOL_ALLOW, чтобы ограничить оба измерения. Правила точные;
подстановочные знаки отклоняются, чтобы вновь добавленное действие не стало разрешённым после обновления.A hosted deployment that cannot install or restart anything
A generation operator that can inspect, enqueue, and cancel—but not install or clear queues
Транспорт
Сервер говорит на stdio по умолчанию (то, что ждёт Claude Code). Он также может обслуживать транспорт streamable-HTTP для удалённых/многоклиентских схем.Run the HTTP transport