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를 명시적으로 설정하세요.
연결
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 자동 감지를 건너뜁니다.로컬 ComfyUI 설치의 절대 경로. 미설정 시 흔한 위치에서 자동 감지됩니다
(원격/클라우드 모드에서는 억제). 로컬 전용 도구에 필요합니다 (노드 설치/관리, 모델
삭제, 로그 읽기, 출력 파일 나열).
main.py와 .venv가 데이터·모델과 다른 루트에 있는 분리 설치의 선택적 코드
checkout 경로입니다. pip / venv / 코어 업데이트가 이 경로를 사용합니다.
custom_nodes 읽기·쓰기는 --base-directory / COMFYUI_PATH에 남습니다.
원격 모드의 로컬 파일 변경에는 사용되지 않습니다.외부에서 관리되는 ComfyUI를 재시작하는 셸 명령 — 예:
docker restart comfyui
또는 systemctl --user restart comfyui. 설정하면 restart_comfyui가
kill+relaunch 대신 이 명령을 실행합니다 (kill+relaunch는 설치의 실행 경로를
해석할 수 있어야 하는데, 컨테이너나 런처에서는 main.py가 자체 네임스페이스
안에서만 앵커되므로 불가능합니다). panel_restart_comfyui도 이 명령을
사용합니다. 로컬 타깃에만 적용되며, 원격/클라우드 타깃은 기존 Manager 재부팅
경로를 유지합니다. 재시작은 인스턴스가 정상으로 돌아왔는지 검증하고, down→up을
실제로 관찰한 경우에만 confirmed로 보고합니다.리버스 프록시 / API 게이트웨이 뒤의 원격
경로 접두사 아래 노출되고/되거나 자체 인증 계층이 있는 셀프호스팅 ComfyUI (nginx 라우트, API 게이트웨이, SSO 에지) — 이것은 Comfy Cloud가 아닙니다:COMFYUI_URL은 경로 접두사를 보존합니다 (예:https://host/comfyapi). 그래서 요청이 루트의/prompt,/system_stats, … 가 아니라 그 아래로 라우팅됩니다.COMFYUI_AUTH_*변수는 모든 ComfyUI 요청에 일반 인증 헤더를 붙입니다 (직접 HTTP 호출과 아래의 클라이언트/WebSocket 라이브러리). 이것은 클라우드 모드와 독립이므로, 게이트웨이 인증된 인스턴스가 Comfy Cloud로 오인되지 않습니다.
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에
더해지며, 둘 다 설정되면 둘 다 적용됩니다. 절대 로그되지 않습니다.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이며 지금 출시 중).토큰
네트워크가 제한된 지역을 위한 HuggingFace 미러 엔드포인트 (예:
https://hf-mirror.com). 모든 huggingface.co API와 다운로드 URL이
이 호스트로 다시 쓰입니다. 게이트된 저장소에는 HUGGINGFACE_TOKEN이 그대로
따라갑니다. 사실상의 표준 변수 — huggingface_hub가 존중하는 것과 같습니다.civitai.com에 닿을 수 없는 지역에서 Civitai 접근을 완전히 끄려면
0으로 설정하세요. 사용자가 시작한 Civitai 도구는 매달리지 않고
명확한 “disabled by config” 메시지로 빨리 실패합니다. 백그라운드 출처 조회는
조용히 no-op합니다./prompt extra_data 페이로드를 통해 호스팅 API 노드에 전달되는 comfy.org API 키.
환경 변수가 미설정이면, 키는 ~/.comfy-api-key에서 읽습니다 (잘린 파일
내용. chmod 600 권장) — 비밀을 환경/프로세스 목록 밖에
두는 헤드리스 설정에 편리합니다.node_pack (action: "publish")이 노드 팩을 게시할 때 쓰는 Comfy Registry API 키. comfy-cli에 환경으로 전달되며, 인자나 로그에 절대 넣지 않습니다.동작
모델 다운로드
모델 다운로드용 내용 주소 캐시. 같은 URL의 반복 또는 동시 다운로드가 캐시된 파일을 재사용합니다. 대상 모델 경로는 하드링크(폴백은 복사)로 실체화됩니다.
모델 다운로드 하나당 병렬 연결 수. 단일 연결은 왕복 시간에 묶이고, 다수의 모델 CDN에서는 연결당 속도 제한도 받습니다. 바이트 범위를 병렬로 받으면 두 제약을 모두 넘어섭니다.
1은 이 기능을 끄고 단일 연결로 내려받습니다. 파일 호스트가 바이트 범위 지원을 알리고 프로브 요청으로 이를 증명한 경우에만 사용되며, 그렇지 않으면 이전과 똑같이 단일 연결로 내려받습니다.프로세스 감시 (로컬 설치)
comfyui-mcp가 로컬 ComfyUI 프로세스를 관리할 때restart_comfyui (액션 start와 restart)에 적용됩니다.
시작이 확인되지 않았다고 보고하기 전의 최대 준비 프로브. 기본
1초 간격이면 약 60초 예산입니다. 20에서 올린 이유는, 평범한
커스텀 노드 세트가 있는 ComfyUI가 콜드 스타트에서
/system_stats에
답하는 데 20초보다 오래 걸리는 일이 흔하고, 더 짧은 예산이
건강한 인스턴스가 준비되기 직전에 시작을 미확인으로 보고했기 때문입니다.예산을 다 쓰는 것은 시작이 아직 확인되지 않았다는 뜻이지 — 실패했다는 뜻이 아닙니다.켜면, 예기치 않게 종료된 ComfyUI 프로세스가 자동으로 재시작됩니다. 의도적인
action: "stop"의 restart_comfyui는 절대 재시작되지 않습니다.패널 오케스트레이터와 브리지
comfyui-mcp-panel 사이드바는 패널 오케스트레이터가 구동합니다 — 루프백 WebSocket 브리지를 소유하고 Claude 구독으로 패널 탭마다 자율 Claude Agent SDK 세션을 실행하는 백그라운드 프로세스입니다 (API 키 없음). 패널 팩이 ComfyUI 로드 시 자동으로 시작하므로, 보통 손으로 아무것도 실행하지 않습니다 — 사이드바 패널을 참고하세요. 직접 실행하려면:오케스트레이터의 대기열/렌더 워치독용 렌더 정체 임계값 (초):
이 시간 동안 노드/진행률이 나아가지 않은 실행 중 작업이 정체로 표시되고,
에이전트의 다음 턴 앞에 한 줄 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 퀵 터널 대신 자체 터널 인프라를 운영하려면
셀프호스팅 릴레이를 참고하세요.
원격 https 대상을 제어할 때도 보안 터널로 자동 올리지 않고
평범한 루프백
ws:// 브리지를 강제합니다. 자체 SSH 포트 포워드로
파드에 닿아 (페이지가 이미 루프백 오리진) 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, 팀 프론트엔드 — 에서 운영자는 프롬프트하는 사람이 아닙니다. 도구 프리셋/허용/거부 변수는 모델에서 도구를 완전히 거둡니다: 거둔 도구는 절대 등록되지 않으므로tools/list에 없고,
call_tool에 없으며, 모델은 존재하는지 배우지 못합니다. 액션 허용 목록은
보여야 하는 도구를 위한 더 좁은 동반입니다: 도구는 등록된 채로 남지만,
목록에 없는 액션은 핸들러가 실행되기 전에 거부됩니다.
safe — 머신이나 모델 라이브러리를 바꾸는 도구를 제외한 모든 것.
설치, 삭제, 재시작이 거둬집니다. 렌더는 여전히 동작하고, 그에 딸린
것도 그렇습니다: 생성 대기열 추가, list_api_nodes (유료 크레딧을 쓰는
호스팅 파트너 노드), report_issue (공개 GitHub 이슈를 접수). 공유
프론트엔드의 사용자가 쓰거나 게시하면 안 되면 readonly를 쓰세요.
readonly — 검사만: 렌더를 대기열에 넣지 않고, 아무것도 쓰지 않고, 아무것도 쓰지 않음.
둘 다 라이브 공유 캔버스를 구동하는 panel_* 표면 전체를 거둡니다.거둘 도구 이름, 쉼표 구분. 예:
restart_comfyui,download_model. 끝의
*는 계열을 맞춥니다: train_*. 어떤 프리셋 그리고 허용
목록 위에 적용됩니다.쉼표 구분 허용 목록. 설정되면 표면은 정확히 이 도구입니다 — 거부
규칙이 언급하지 않아도 이름 붙지 않은 것은 거둬집니다. 프리셋을 넘어 개별 도구를
다시 넣으려면:
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: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 트랜스포트도 제공할 수 있습니다.Run the HTTP transport