env do servidor em ~/.claude/settings.json) ou flags da CLI. Precedência
para o alvo do ComfyUI:
--comfyui-url / COMFYUI_URL → COMFYUI_HOST/COMFYUI_PORT → detecção
automática.
Modos de implantação
Ocomfyui-mcp opera em um de três modos, auto-selecionado a partir do
ambiente:
Ferramentas que exigem uma instalação local (
restart_comfyui com action: "start" / apply_manifest / list_local_models (action:"remove") / get_image (action:"list_outputs") / etc.)
retornam um erro claro quando rodam em modo remoto ou cloud. Nos modos
remoto e cloud o servidor pula a detecção automática local de
COMFYUI_PATH para que uma instalação local desatualizada não absorva em
silêncio uploads ou downloads de modelos que o agente destina ao alvo de
verdade — defina COMFYUI_PATH explicitamente se quiser misturar.
Conexão
URL completa da instância do ComfyUI, por exemplo
https://my-comfy.example.com. Equivalente à
flag CLI --comfyui-url. Tem precedência sobre host/porta e pula a detecção automática de porta.
Um prefixo de caminho é preservado (por exemplo https://host/comfyapi) para que instâncias
atrás de reverse-proxy sejam roteadas corretamente. Quando o host não é loopback (qualquer coisa
além de 127.0.0.1 / localhost / ::1 / 0.0.0.0), o servidor entra em modo remoto e
pula a detecção automática de COMFYUI_PATH.Caminho absoluto da instalação local do ComfyUI. Auto-detectado a partir de locais comuns quando
não definido (suprimido nos modos remoto/cloud). Exigido pelas ferramentas só locais
(instalar/gerenciar nós, remover modelos, ler logs, listar arquivos de saída).
Raiz opcional do checkout de código para instalações separadas, em que
main.py
e .venv ficam longe dos dados e modelos. Pip, venv e atualizações do núcleo
usam este checkout. Leituras/escritas de packs (custom_nodes) permanecem em
--base-directory / COMFYUI_PATH. Ignorado em modo remoto.Comando de shell que reinicia um ComfyUI gerenciado externamente — ex.
docker restart comfyui ou systemctl --user restart comfyui. Quando
definido, o restart_comfyui executa esse comando em vez de kill+relaunch
(que exige que o caminho de inicialização da instalação seja resolvível —
impossível para um contêiner ou launcher cujo main.py só se ancora dentro
do próprio namespace), e o panel_restart_comfyui também passa por ele.
Apenas alvos locais; alvos remotos/cloud mantêm o caminho de reboot via
Manager. O restart verifica que a instância voltou saudável e só reporta o
ciclo como confirmado quando o down→up foi de fato observado.Remoto atrás de um reverse proxy / gateway de API
Para um ComfyUI auto-hospedado exposto sob um prefixo de caminho e/ou a própria camada de auth (uma rota nginx, um gateway de API, uma borda SSO) — isto não é o Comfy Cloud:COMFYUI_URLpreserva um prefixo de caminho (por exemplohttps://host/comfyapi), então as requisições são roteadas embaixo dele em vez de bater em/prompt,/system_stats, … na raiz.- As variáveis
COMFYUI_AUTH_*anexam um cabeçalho de auth genérico a toda requisição do ComfyUI (as chamadas HTTP diretas e a biblioteca cliente/WebSocket por baixo). Isto é independente do modo cloud, então uma instância autenticada por gateway nunca é lida por engano como Comfy Cloud.
Token de auth para um ComfyUI auto-hospedado atrás de um gateway. Quando definido, enviado em
toda requisição do ComfyUI. Nunca registrado em log.
Prefixo de esquema no valor do token, por exemplo
Bearer, Token.Client ID do service token do Cloudflare Access. Defina junto com
CF_ACCESS_CLIENT_SECRET para alcançar um ComfyUI na frente do Cloudflare Access — os dois
são enviados (como CF-Access-Client-Id / CF-Access-Client-Secret) em toda
requisição do ComfyUI (HTTP e o WebSocket do observador de fila), então o conector passa
o portão do Access em vez de receber a página interativa de login. Aditivo a
COMFYUI_AUTH_TOKEN; os dois valem se os dois estiverem definidos. Nunca registrado em log.Client Secret do service token do Cloudflare Access (o par de
CF_ACCESS_CLIENT_ID).
Só é enviado quando os dois estão definidos — um token pela metade é ignorado. Nunca
registrado em log.Comfy Cloud
DefinirCOMFYUI_API_KEY coloca o servidor em modo cloud: todas as
primitivas apoiadas em HTTP (enqueue, history, system stats, queue, view,
upload) são roteadas para cloud.comfy.org via HTTPS com autenticação
X-API-Key; ferramentas de WebSocket e de FS/processo local lançam um
erro claro CLOUD_UNSUPPORTED. Arquitetura e o dispatcher cloud-client
originalmente contribuídos por
@picoSols.
A Comfy-Org entrega ferramental oficial para agentes — o Comfy Cloud MCP (beta pública) e o Comfy In-App Agent (alfa privada), ambos mantidos pelo time da Comfy e ambos rodando no Comfy Cloud. Se você só mira o Comfy Cloud, essa provavelmente é a escolha certa; veja Local vs. Comfy Cloud. O modo cloud do
comfyui-mcp abaixo é melhor quando você quer um único MCP para local / remoto / nuvem, ou precisa disso hoje (é MIT e já está saindo).Chave de API do Comfy Cloud. Quando definida, o servidor entra em modo cloud e fala com a URL
de nuvem configurada em vez de um ComfyUI local. Nunca registrada em log.
Sobrescreve o endpoint do Comfy Cloud (principalmente para teste / staging).
Tokens
Token de API do CivitAI. Usado para downloads protegidos/early-access. Enviado como cabeçalho
bearer (nunca em URLs).
Endpoint de espelho do HuggingFace para regiões com rede restrita (por exemplo
https://hf-mirror.com). Todas as URLs de API e download de huggingface.co são
reescritas para este host; o seu HUGGINGFACE_TOKEN ainda viaja junto para repositórios
protegidos. A variável de fato padrão — a mesma que o huggingface_hub honra.Defina como
0 para desativar o acesso ao Civitai por completo (regiões em que
civitai.com é inalcançável). Ferramentas Civitai iniciadas pelo usuário falham rápido com
uma mensagem clara de “disabled by config” em vez de pendurar; buscas de proveniência em
segundo plano viram no-op em silêncio.Token do GitHub usado pela geração de skills e pelas buscas de metadados de nós para evitar
limites de taxa.
Chave de API do comfy.org encaminhada a nós de API hospedados pelo payload
extra_data de
/prompt. Se a variável de ambiente não estiver definida, a chave é lida de
~/.comfy-api-key (conteúdo do arquivo aparado; chmod 600 recomendado) — útil para
setups headless que mantêm segredos fora de listagens de ambiente/processo.Chave de API do Comfy Registry usada por
node_pack (action: "publish") para publicar um
pacote de nós. Passada ao comfy-cli via env, nunca colocada em args ou logs.Comportamento
Diretório varrido em busca de workflows
*.json. Cada um vira uma ferramenta de execução
auto-carregada.Downloads de modelos
Cache endereçado por conteúdo para downloads de modelos. Downloads repetidos ou concorrentes
da mesma URL reaproveitam o arquivo em cache; o caminho de modelo de destino é materializado
via hardlink (caindo para cópia).
Tamanho máximo do cache de download em GB.
0 desativa a evicção; acima do limite, os
arquivos em cache menos usados recentemente são apagados depois que um download termina.Conexões paralelas por download de modelo. Uma única conexão é limitada pelo tempo de ida e volta e, em muitas CDNs de modelos, por um limite de taxa por conexão; buscar intervalos de bytes em paralelo supera os dois.
1 desativa o recurso e baixa por uma única conexão. Usado apenas quando o host anuncia suporte a intervalos de bytes e o comprova em uma requisição de sondagem — caso contrário, o download ocorre por uma única conexão exatamente como antes.Tamanho mínimo de arquivo, em MB, que vale dividir entre várias conexões. Abaixo disso, as requisições extras custam mais do que o paralelismo devolve.
Supervisão de processos (instalações locais)
Aplica-se arestart_comfyui (ações start e restart) quando o
comfyui-mcp gerencia um processo local do ComfyUI.
Máximo de sondas de prontidão antes de reportar que a inicialização não está confirmada. Com o
intervalo padrão de 1s isso é um orçamento de ~60s. Foi elevado de 20 porque o ComfyUI
com um conjunto normal de nós personalizados rotineiramente leva mais de 20s para responder
/system_stats num cold start, e o orçamento menor reportava uma inicialização como
não confirmada momentos antes de uma instância saudável ficar pronta.Esgotar o orçamento significa que a inicialização ainda não está confirmada — não que
falhou.Quando habilitado, um processo do ComfyUI que sai de forma inesperada é reiniciado
automaticamente. Um
restart_comfyui deliberado com action: "stop" nunca é reiniciado.Janela deslizante (segundos) sobre a qual as tentativas de auto-reinício são contadas.
Orquestrador do painel e a ponte
A barra lateral do comfyui-mcp-panel é conduzida pelo orquestrador do painel — um processo em segundo plano que possui uma ponte WebSocket de loopback e roda uma sessão autônoma do Claude Agent SDK por aba do painel na sua assinatura do Claude (sem chaves de API). O pacote do painel o inicia automaticamente no carregamento do ComfyUI, então em geral você não roda nada na mão — veja Painel lateral. Para rodá-lo você mesmo:Rodar o orquestrador do painel em vez de um servidor MCP (o mesmo que
--panel-orchestrator).Porta de loopback da ponte WebSocket do painel que o orquestrador do painel
possui (padrão 9199).
Limiar de stall de renderização (segundos) do watchdog de fila/renderização do orquestrador: um
job em execução cujo nó/progresso não avançou por esse tempo é marcado como stalled,
e uma nota de uma linha STALL/BACKLOG é prefixada no próximo turno do agente. Passos de vídeo
são legitimamente lentos, então o padrão é alto. Limitado a 15–3600s. A configuração
Aviso de renderização travada (segundos) do painel (Configurações → Comfy MCP Agent → Geral)
sobrescreve isto ao vivo via um frame
set_config da ponte — sem precisar reconectar —
tendo precedência sobre este valor de env.Ponte segura (controlando um pod remoto/nuvem)
Quandoconnect <url> mira um ComfyUI https remoto (por exemplo um pod
RunPod), a página HTTPS do painel no pod não consegue abrir um socket
ws://127.0.0.1 simples para a ponte na sua máquina — os navegadores
bloqueiam (mixed content / Private Network Access). O orquestrador
atualiza automaticamente para um túnel wss:// seguro para funcionar sem
prompt, em qualquer navegador. Veja Implantação na nuvem
para o passo a passo completo e Relay auto-hospedado
para rodar a sua própria infraestrutura de túnel em vez do túnel rápido
padrão do cloudflared.
Forçar a ponte de loopback
ws:// simples mesmo ao conduzir um alvo https
remoto, em vez de atualizar automaticamente para um túnel seguro. Use isto se você alcança
o pod pelo seu próprio encaminhamento de porta SSH (então a página dele já é uma origem
de loopback) e não quer uma dependência do Cloudflare. O mesmo que --insecure-bridge.Qual backend de ponte segura usar para um alvo remoto:
cloudflared (padrão
— um túnel rápido efêmero, zero configuração) ou relay (discar um
relay auto-hospedado que você opera, para um domínio
estável e sem dependência de túnel rápido de terceiros). Só vale quando o modo seguro está
ativo (alvo https remoto, não COMFYUI_MCP_INSECURE_BRIDGE).Segredo compartilhado opcional que controla quem pode abrir uma sessão no seu relay de
qualquer forma (
?key=), independente do token de ponte por sessão. Só relevante no modo
relay, e só se a implantação do seu relay definir RELAY_ACCESS_KEY.Acompanhamento de jobs
Notificações de conclusão para jobs enfileirados são acompanhadas por um observador (WebSocket quando disponível, sondagem HTTP caso contrário).Máximo de segundos que o observador espera um job completar antes de desistir. Suba isto
para renderizações de vídeo muito longas ou workflows pesados de vários estágios. (O próprio
job continua rodando no ComfyUI — só a notificação de conclusão é abandonada.)
Janela de honra do cancelamento (segundos) para
queue (action:“cancel”): quanto esperar
para um interrupt de fato parar o job em execução antes de escalar (para /free, depois
reportar a renderização WEDGED). O ComfyUI só checa a flag de interrupt entre nós/passos,
então um único passo de vários minutos não vai honrá-la na hora — esta espera é o que
detecta um emperramento de verdade.Restringindo o conjunto de ferramentas
Para uma implantação hospedada — um Open WebUI compartilhado, um front-end de time — o operador não é a pessoa que está pedindo. As variáveis de preset/allow/deny de ferramentas retêm ferramentas do modelo por completo: uma ferramenta retida nunca é registrada, então está ausente detools/list, ausente de call_tool, e o modelo nunca
descobre que ela existe. A lista de permissão de ações é a companheira
mais estreita para uma ferramenta que precisa continuar visível: a
ferramenta permanece registrada, mas uma ação não listada é rejeitada
antes de o handler rodar.
safe — tudo, menos as ferramentas que mudam a máquina ou a biblioteca de modelos.
Instalar, apagar e reiniciar são retidos. Renderizar ainda funciona, e também as
coisas que vêm junto: enfileirar gerações, list_api_nodes (nós parceiros hospedados
que gastam créditos PAGOS), e report_issue (abre uma issue pública no GitHub). Use
readonly se os usuários de um front-end compartilhado não puderem gastar nem publicar.
readonly — só inspeção: nenhuma renderização enfileirada, nada escrito, nada gasto.
Os dois também retêm a superfície panel_* inteira, que conduz um canvas compartilhado
ao vivo.Nomes de ferramentas separados por vírgula para reter, por exemplo
restart_comfyui,download_model. Um
* no final casa uma família: train_*. Aplicado por cima de qualquer preset e por cima
de uma lista de permissão.Lista de permissão separada por vírgula. Quando definida, a superfície é exatamente estas
ferramentas — qualquer coisa não nomeada é retida mesmo se nenhuma regra de deny a mencionar.
Use para readmitir ferramentas individuais além de um preset:
COMFYUI_MCP_TOOL_PRESET=safe mais
COMFYUI_MCP_TOOL_ALLOW=panel_graph_outline,panel_query_graph.Só um nome exato readmite uma ferramenta além de um preset. Um glob (list_*) estreita a
superfície como qualquer outra entrada mas não consegue reabrir o que um preset fechou — senão
ALLOW=list_* readmitiria list_packs, cuja ação install_deps instala e
roda código de terceiros, e ALLOW=* tornaria todo preset inerte.Pares
tool:action exatos, separados por vírgula. Quando definido, toda chamada de ferramenta
carregando um campo action precisa casar com um desses pares; ferramentas com ação omitidas
da lista não conseguem despachar ação nenhuma. Isto restringe ferramentas consolidadas cujos
nomes sozinhos já não revelam o raio de explosão — por exemplo, permitir inspeção da fila e
cancelamento pontual sem também permitir edições da fila ou um clear global:queue:list,queue:status,queue:cancel,enqueue_workflow:enqueueCombine isto com COMFYUI_MCP_TOOL_ALLOW para limitar as duas dimensões. As regras são exatas;
wildcards são rejeitados para que uma ação recém-adicionada não se torne permitida depois de
uma atualização.A hosted deployment that cannot install or restart anything
A generation operator that can inspect, enqueue, and cancel—but not install or clear queues
Transporte
O servidor fala stdio por padrão (o que o Claude Code espera). Também pode servir o transporte streamable-HTTP para setups remotos/multi-cliente.Run the HTTP transport