env 블록,
~/.claude/settings.json) 또는 CLI 플래그입니다. ComfyUI 대상의 우선순위:
--comfyui-url / COMFYUI_URL → COMFYUI_HOST/COMFYUI_PORT → 자동 감지.
배포 모드
comfyui-mcp는 환경에서 자동 선택되는 세 모드 중 하나로 동작합니다:
로컬 설치가 필요한 도구(
action: "start"의 restart_comfyui / apply_manifest / list_local_models (action:"remove") / get_image (action:"list_outputs") / 등)는
원격 또는 클라우드 모드에서 명확한 오류를 반환합니다. 원격과 클라우드 모드에서 서버는
로컬 COMFYUI_PATH 자동 감지를 건너뛰어, 오래된 로컬 설치가 에이전트가 실제 대상으로 의도한
업로드나 모델 다운로드를 조용히 가로채지 못하게 합니다 — 섞어 쓰고 싶으면
COMFYUI_PATH를 명시적으로 설정하세요.
연결
string
ComfyUI 인스턴스의 전체 URL, 예:
https://my-comfy.example.com. --comfyui-url
CLI 플래그와 같습니다. 호스트/포트보다 우선하며 포트 자동 감지를 건너뜁니다.
경로 접두사가 보존됩니다 (예: https://host/comfyapi). 리버스 프록시된 인스턴스가
올바르게 라우팅됩니다. 호스트가 루프백이 아니면 (127.0.0.1 / localhost /
::1 / 0.0.0.0 외의 모든 것), 서버가 원격 모드로 들어가 COMFYUI_PATH 자동 감지를 건너뜁니다.string
기본값:"127.0.0.1"
ComfyUI 서버의 호스트.
number
ComfyUI 서버의 포트. 미설정 시 자동 감지 (8188, 그다음 8000).
boolean
기본값:"false"
http/ws 대신 https/wss를 사용합니다.string
로컬 ComfyUI 설치의 절대 경로. 미설정 시 흔한 위치에서 자동 감지됩니다
(원격/클라우드 모드에서는 억제). 로컬 전용 도구에 필요합니다 (노드 설치/관리, 모델
삭제, 로그 읽기, 출력 파일 나열).
리버스 프록시 / API 게이트웨이 뒤의 원격
경로 접두사 아래 노출되고/되거나 자체 인증 계층이 있는 셀프호스팅 ComfyUI (nginx 라우트, API 게이트웨이, SSO 에지) — 이것은 Comfy Cloud가 아닙니다:COMFYUI_URL은 경로 접두사를 보존합니다 (예:https://host/comfyapi). 그래서 요청이 루트의/prompt,/system_stats, … 가 아니라 그 아래로 라우팅됩니다.COMFYUI_AUTH_*변수는 모든 ComfyUI 요청에 일반 인증 헤더를 붙입니다 (직접 HTTP 호출과 아래의 클라이언트/WebSocket 라이브러리). 이것은 클라우드 모드와 독립이므로, 게이트웨이 인증된 인스턴스가 Comfy Cloud로 오인되지 않습니다.
string
게이트웨이 뒤 셀프호스팅 ComfyUI용 인증 토큰. 설정되면 모든 ComfyUI
요청에 보내집니다. 절대 로그되지 않습니다.
string
기본값:"Authorization"
토큰을 실어 나르는 헤더 이름, 예:
X-API-Key.string
기본값:"Bearer for Authorization, else none"
토큰 값의 스킴 접두사, 예:
Bearer, Token.string
Cloudflare Access 서비스 토큰 Client ID.
CF_ACCESS_CLIENT_SECRET과
함께 설정하면 Cloudflare Access가 앞선 ComfyUI에 닿습니다 — 둘 다
모든 ComfyUI 요청(HTTP와 대기열 감시자 WebSocket)에
(CF-Access-Client-Id / CF-Access-Client-Secret으로) 보내져, 커넥터가
인터랙티브 로그인 페이지 대신 Access 게이트를 통과합니다. COMFYUI_AUTH_TOKEN에
더해지며, 둘 다 설정되면 둘 다 적용됩니다. 절대 로그되지 않습니다.string
Cloudflare Access 서비스 토큰 Client Secret (
CF_ACCESS_CLIENT_ID의 짝).
둘 다 설정되었을 때만 보내집니다 — 반만 설정된 토큰은 무시됩니다. 절대 로그되지 않습니다.Comfy Cloud
COMFYUI_API_KEY를 설정하면 서버가 클라우드 모드로 전환됩니다: 모든 HTTP 기반 원시
(대기열 추가, 히스토리, 시스템 통계, 대기열, 보기, 업로드)가 HTTPS 위의 cloud.comfy.org로
X-API-Key 인증과 함께 라우팅됩니다. WebSocket과 로컬 FS/프로세스 도구는 명확한 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이며 지금 출시 중).string
Comfy Cloud API 키. 설정되면 서버가 클라우드 모드로 들어가 로컬 ComfyUI 대신
설정된 클라우드 URL과 대화합니다. 절대 로그되지 않습니다.
string
기본값:"https://cloud.comfy.org"
Comfy Cloud 엔드포인트를 재정의합니다 (주로 테스트 / 스테이징).
토큰
string
CivitAI API 토큰. 게이트/얼리액세스 다운로드에 쓰입니다. bearer 헤더로 보내집니다 (URL에는 절대 없음).
string
더 높은 검색/다운로드 속도 제한을 위한 HuggingFace 토큰.
string
네트워크가 제한된 지역을 위한 HuggingFace 미러 엔드포인트 (예:
https://hf-mirror.com). 모든 huggingface.co API와 다운로드 URL이
이 호스트로 다시 쓰입니다. 게이트된 저장소에는 HUGGINGFACE_TOKEN이 그대로
따라갑니다. 사실상의 표준 변수 — huggingface_hub가 존중하는 것과 같습니다.string
civitai.com에 닿을 수 없는 지역에서 Civitai 접근을 완전히 끄려면
0으로 설정하세요. 사용자가 시작한 Civitai 도구는 매달리지 않고
명확한 “disabled by config” 메시지로 빨리 실패합니다. 백그라운드 출처 조회는
조용히 no-op합니다.string
속도 제한을 피하기 위해 스킬 생성과 노드 메타데이터 가져오기가 쓰는 GitHub 토큰.
string
/prompt extra_data 페이로드를 통해 호스팅 API 노드에 전달되는 comfy.org API 키.
환경 변수가 미설정이면, 키는 ~/.comfy-api-key에서 읽습니다 (잘린 파일
내용. chmod 600 권장) — 비밀을 환경/프로세스 목록 밖에
두는 헤드리스 설정에 편리합니다.string
node_pack (action: "publish")이 노드 팩을 게시할 때 쓰는 Comfy Registry API 키. comfy-cli에 환경으로 전달되며, 인자나 로그에 절대 넣지 않습니다.동작
string
기본값:"~/.comfyui-mcp/workflows"
*.json 워크플로우를 스캔하는 디렉터리. 각각이 자동 로드된 실행 도구가 됩니다.string
기본값:"info"
로깅 상세도:
debug, info, warn, error.모델 다운로드
string
기본값:"~/.comfyui-mcp/cache"
모델 다운로드용 내용 주소 캐시. 같은 URL의 반복 또는 동시 다운로드가 캐시된 파일을 재사용합니다. 대상 모델 경로는 하드링크(폴백은 복사)로 실체화됩니다.
number
기본값:"0"
다운로드 캐시의 최대 크기(GB).
0은 퇴거를 끕니다. 한도를 넘으면 다운로드가 끝난 뒤 가장 오래 쓰이지 않은 캐시 파일이 삭제됩니다.프로세스 감시 (로컬 설치)
comfyui-mcp가 로컬 ComfyUI 프로세스를 관리할 때restart_comfyui (액션 start와 restart)에 적용됩니다.
number
기본값:"1"
ComfyUI를 띄운 뒤 준비 프로브 사이의 초.
number
기본값:"60"
시작이 확인되지 않았다고 보고하기 전의 최대 준비 프로브. 기본
1초 간격이면 약 60초 예산입니다. 20에서 올린 이유는, 평범한
커스텀 노드 세트가 있는 ComfyUI가 콜드 스타트에서
/system_stats에
답하는 데 20초보다 오래 걸리는 일이 흔하고, 더 짧은 예산이
건강한 인스턴스가 준비되기 직전에 시작을 미확인으로 보고했기 때문입니다.예산을 다 쓰는 것은 시작이 아직 확인되지 않았다는 뜻이지 — 실패했다는 뜻이 아닙니다.boolean
기본값:"false"
켜면, 예기치 않게 종료된 ComfyUI 프로세스가 자동으로 재시작됩니다. 의도적인
action: "stop"의 restart_comfyui는 절대 재시작되지 않습니다.number
기본값:"3"
포기하기 전 재시작 창 안에서 허용되는 최대 자동 재시작.
number
기본값:"60"
자동 재시작 시도가 세어지는 슬라이딩 창 (초).
패널 오케스트레이터와 브리지
comfyui-mcp-panel 사이드바는 패널 오케스트레이터가 구동합니다 — 루프백 WebSocket 브리지를 소유하고 Claude 구독으로 패널 탭마다 자율 Claude Agent SDK 세션을 실행하는 백그라운드 프로세스입니다 (API 키 없음). 패널 팩이 ComfyUI 로드 시 자동으로 시작하므로, 보통 손으로 아무것도 실행하지 않습니다 — 사이드바 패널을 참고하세요. 직접 실행하려면:boolean
기본값:"false"
MCP 서버 대신 패널 오케스트레이터를 실행합니다 (
--panel-orchestrator와 같음).string
기본값:"claude-opus-5"
백그라운드 패널 에이전트용 모델.
number
기본값:"9180"
패널 오케스트레이터가 소유하는 패널 WebSocket 브리지의
루프백 포트 (기본값 9180).
number
기본값:"180"
오케스트레이터의 대기열/렌더 워치독용 렌더 정체 임계값 (초):
이 시간 동안 노드/진행률이 나아가지 않은 실행 중 작업이 정체로 표시되고,
에이전트의 다음 턴 앞에 한 줄 STALL/BACKLOG 노트가 붙습니다. 비디오 단계는
정당하게 느리므로 기본값이 높습니다. 15–3600초로 고정됩니다. 패널의
렌더 정체 경고 (초) 설정 (설정 → Comfy MCP Agent → 일반)이
set_config 브리지 프레임으로 이것을 실시간 재정의합니다 — 다시 연결할 필요 없음 —
이 환경 값보다 우선합니다.보안 브리지 (원격/클라우드 파드 제어)
connect <url>이 원격 https ComfyUI (예: RunPod 파드)를 대상으로 하면,
파드의 HTTPS 패널 페이지가 머신의 브리지로 평범한 ws://127.0.0.1 소켓을
열 수 없습니다 — 브라우저가 차단합니다 (혼합 콘텐츠 / Private Network Access).
오케스트레이터가 자동으로 보안 wss:// 터널로 올려, 프롬프트 없이
어떤 브라우저에서든 동작합니다. 전체 절차는 클라우드 배포,
기본 cloudflared 퀵 터널 대신 자체 터널 인프라를 운영하려면
셀프호스팅 릴레이를 참고하세요.
boolean
기본값:"false"
원격 https 대상을 제어할 때도 보안 터널로 자동 올리지 않고
평범한 루프백
ws:// 브리지를 강제합니다. 자체 SSH 포트 포워드로
파드에 닿아 (페이지가 이미 루프백 오리진) Cloudflare 의존성을
원하지 않을 때 쓰세요. --insecure-bridge와 같습니다.string
기본값:"cloudflared"
원격 대상에 쓸 보안 브리지 백엔드:
cloudflared (기본값
— 일시적 퀵 터널, 설정 없음) 또는 relay (직접 운영하는
셀프호스팅 릴레이에 전화, 안정적인 도메인과
서드파티 퀵 터널 의존성 없음). 보안 모드가 활성일 때만
적용됩니다 (원격 https 대상, COMFYUI_MCP_INSECURE_BRIDGE 아님).string
릴레이의
wss:// URL. COMFYUI_MCP_TUNNEL_BACKEND=relay일 때 필수.string
릴레이에서 세션을 열 수 있는 사람을 게이트하는 선택적 공유 비밀
(
?key=). 세션별 브리지 토큰과 독립. 릴레이
모드에서만, 그리고 릴레이 배포가 RELAY_ACCESS_KEY를 설정한 경우에만 관련됩니다.작업 감시
대기열에 넣은 작업의 완료 알림은 감시자가 추적합니다 (가능한 경우 WebSocket, 아니면 HTTP 폴링).number
기본값:"1800"
감시자가 작업을 포기하기 전에 완료를 기다리는 최대 초. 매우 긴
비디오 렌더나 무거운 다단계 워크플로우에는 올리세요. (작업 자체는 ComfyUI에서
계속 실행됩니다 — 완료 알림만 버려집니다.)
number
기본값:"2"
작업을 감시하는 동안 HTTP 히스토리 폴링 사이의 초.
number
기본값:"30"
queue (action:“cancel”)의 취소 존중 창 (초): 인터럽트가
실행 중 작업을 실제로 멈출 때까지 기다린 뒤 격상하기 (/free로, 그다음 렌더를
WEDGED로 보고). ComfyUI는 노드/단계 사이에서만 인터럽트 플래그를 확인하므로, 수 분의
단일 단계는 즉시 존중하지 않습니다 — 이 대기가 진짜 정체를 감지합니다.도구 표면 제한하기
호스팅 배포 — 공유 Open WebUI, 팀 프론트엔드 — 에서 운영자는 프롬프트하는 사람이 아닙니다. 도구 프리셋/허용/거부 변수는 모델에서 도구를 완전히 거둡니다: 거둔 도구는 절대 등록되지 않으므로tools/list에 없고,
call_tool에 없으며, 모델은 존재하는지 배우지 못합니다. 액션 허용 목록은
보여야 하는 도구를 위한 더 좁은 동반입니다: 도구는 등록된 채로 남지만,
목록에 없는 액션은 핸들러가 실행되기 전에 거부됩니다.
string
safe — 머신이나 모델 라이브러리를 바꾸는 도구를 제외한 모든 것.
설치, 삭제, 재시작이 거둬집니다. 렌더는 여전히 동작하고, 그에 딸린
것도 그렇습니다: 생성 대기열 추가, list_api_nodes (유료 크레딧을 쓰는
호스팅 파트너 노드), report_issue (공개 GitHub 이슈를 접수). 공유
프론트엔드의 사용자가 쓰거나 게시하면 안 되면 readonly를 쓰세요.
readonly — 검사만: 렌더를 대기열에 넣지 않고, 아무것도 쓰지 않고, 아무것도 쓰지 않음.
둘 다 라이브 공유 캔버스를 구동하는 panel_* 표면 전체를 거둡니다.string
거둘 도구 이름, 쉼표 구분. 예:
restart_comfyui,download_model. 끝의
*는 계열을 맞춥니다: train_*. 어떤 프리셋 그리고 허용
목록 위에 적용됩니다.string
쉼표 구분 허용 목록. 설정되면 표면은 정확히 이 도구입니다 — 거부
규칙이 언급하지 않아도 이름 붙지 않은 것은 거둬집니다. 프리셋을 넘어 개별 도구를
다시 넣으려면:
COMFYUI_MCP_TOOL_PRESET=safe 더하기
COMFYUI_MCP_TOOL_ALLOW=panel_graph_outline,panel_query_graph.프리셋을 넘어 도구를 다시 넣는 것은 정확한 이름뿐입니다. 글로브 (list_*)는
다른 항목처럼 표면을 좁히지만 프리셋이 닫은 것을 다시 열 수 없습니다 — 그렇지 않으면
ALLOW=list_*가 list_packs를 다시 들이고, 그 install_deps 액션이 서드파티
코드를 설치하고 실행하며, ALLOW=*는 모든 프리셋을 무력하게 만듭니다.string
쉼표 구분, 정확한
tool:action 쌍. 설정되면 action 필드를 실어 나르는
모든 도구 호출이 이 쌍 중 하나와 맞아야 합니다. 목록에서 빠진 액션을 가진
도구는 어떤 액션도 디스패치할 수 없습니다. 이름만으로는 폭발 반경이 더 이상
드러나지 않는 통합 도구를 제한합니다—예를 들어, 대기열 검사와 대상
취소를 허용하면서 대기열 편집이나 전역 지우기는 허용하지 않기:queue:list,queue:status,queue:cancel,enqueue_workflow:enqueueCOMFYUI_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 트랜스포트도 제공할 수 있습니다.string
기본값:"stdio"
stdio 또는 http. 동등한 플래그: --stdio, --http.string
기본값:"127.0.0.1"
HTTP 바인드 호스트 (
--http와 함께). 플래그: --host.number
기본값:"9100"
HTTP 바인드 포트 (
--http와 함께). 플래그: --port.Run the HTTP transport