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
string
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.string
padrão:"127.0.0.1"
Host do servidor ComfyUI.
number
Porta do servidor ComfyUI. Auto-detectada (8188, depois 8000) quando não definida.
boolean
padrão:"false"
Usar
https/wss em vez de http/ws.string
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).
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.
string
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.
string
padrão:"Authorization"
Nome do cabeçalho que carrega o token, por exemplo
X-API-Key.string
padrão:"Bearer for Authorization, else none"
Prefixo de esquema no valor do token, por exemplo
Bearer, Token.string
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.string
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).string
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.
string
padrão:"https://cloud.comfy.org"
Sobrescreve o endpoint do Comfy Cloud (principalmente para teste / staging).
Tokens
string
Token de API do CivitAI. Usado para downloads protegidos/early-access. Enviado como cabeçalho
bearer (nunca em URLs).
string
Token do HuggingFace para limites de taxa maiores de busca/download.
string
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.string
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.string
Token do GitHub usado pela geração de skills e pelas buscas de metadados de nós para evitar
limites de taxa.
string
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.string
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
string
padrão:"~/.comfyui-mcp/workflows"
Diretório varrido em busca de workflows
*.json. Cada um vira uma ferramenta de execução
auto-carregada.string
padrão:"info"
Verbosidade do log:
debug, info, warn, error.Downloads de modelos
string
padrão:"~/.comfyui-mcp/cache"
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).
number
padrão:"0"
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.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.
number
padrão:"1"
Segundos entre sondas de prontidão depois de lançar o ComfyUI.
number
padrão:"60"
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.boolean
padrão:"false"
Quando habilitado, um processo do ComfyUI que sai de forma inesperada é reiniciado
automaticamente. Um
restart_comfyui deliberado com action: "stop" nunca é reiniciado.number
padrão:"3"
Máximo de auto-reinícios permitidos dentro da janela de reinício antes de desistir.
number
padrão:"60"
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:boolean
padrão:"false"
Rodar o orquestrador do painel em vez de um servidor MCP (o mesmo que
--panel-orchestrator).string
padrão:"claude-opus-5"
Modelo para os agentes do painel em segundo plano.
number
padrão:"9180"
Porta de loopback da ponte WebSocket do painel que o orquestrador do painel
possui (padrão 9180).
number
padrão:"180"
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.
boolean
padrão:"false"
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.string
padrão:"cloudflared"
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).string
A URL
wss:// do seu relay. Obrigatória quando COMFYUI_MCP_TUNNEL_BACKEND=relay.string
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).number
padrão:"1800"
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.)
number
padrão:"2"
Segundos entre sondagens HTTP de histórico enquanto um job está sendo acompanhado.
number
padrão:"30"
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.
string
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.string
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.string
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.string
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.string
padrão:"stdio"
stdio ou http. Flags equivalentes: --stdio, --http.string
padrão:"127.0.0.1"
Host de bind HTTP (com
--http). Flag: --host.number
padrão:"9100"
Porta de bind HTTP (com
--http). Flag: --port.Run the HTTP transport