머릿속 모델
ComfyUI MCP는 실행 중인 ComfyUI 인스턴스 위의 얇고 잘 기술된 계층입니다. 대부분의 도구는 그 인스턴스의 HTTP/WebSocket API로 대화하므로, ComfyUI가 로컬이든, 원격 (--comfyui-url)이든, Comfy Cloud (COMFYUI_API_KEY)든
똑같이 동작합니다.
1
생성과 워크플로우 → ComfyUI HTTP API
generate_image, enqueue_workflow, 대기열/히스토리/시스템 통계, 그리고 워크플로우
작성 도구는 ComfyUI의 /prompt, /queue, /history, /object_info 등을 호출합니다.
대기열 추가는 fire-and-forget입니다: prompt_id를 즉시 받고 결과는
완료 알림으로 도착합니다. 클라우드 모드에서는 대체 cloud-client가 같은
작업을 X-API-Key로 cloud.comfy.org에 보냅니다.2
커스텀 노드와 모델 → ComfyUI-Manager (HTTP), 서브프로세스 폴백
노드 설치/업데이트/스냅샷/바이섹트와 워크플로우 의존성 설치는
ComfyUI-Manager HTTP API를 우선 사용하고
(원격 인스턴스에서도 동작하도록), API가 할 수 없는 일은 로컬 설치에 대해
cm-cli / git / pip/uv로 폴백합니다.3
설치와 파일시스템 작업 → 로컬 전용
ComfyUI 설치, 코어 업데이트, 모델 파일 삭제, 서버 로그 읽기, 출력
디렉터리 나열은 로컬 파일시스템에서 동작합니다. 알려진
COMFYUI_PATH가 필요하며 원격 또는 클라우드 모드에서는 명확한 오류를 반환합니다.4
WebSocket → 로컬 + 원격, 클라우드는 아님
작업 완료 알림은 가능한 경우 ComfyUI의 WebSocket에 붙습니다. Comfy Cloud에는
WebSocket이 없습니다 — 작업 감시자가 기존 HTTP 폴링 경로로 넘어갑니다.
경험 법칙: 연결된 서버를 읽거나 실행하는 것은 어떤 모드에서든 동작하고,
소프트웨어를 설치하거나 디스크의 파일을 건드리는 것은 로컬 설치가 필요합니다.
전체 기능 대응표는 설정 → 배포 모드에 있습니다.
자가 치유: 대기열/렌더 워치독
정체된 고해상도 샘플러 단계가 에이전트로 하여금, 보지도 죽이지도 못하는 좀비 렌더 뒤에 작업을 쌓게 만들곤 했습니다. 세 가지 최선을 다하는 가드가 그 틈을 막아, 에이전트가 멈춘 렌더 뒤에 무작정 다시 대기열에 넣지 않게 합니다:- 배압 —
panel_run은 렌더가 이미 실행 중이면 결과에 QUEUE WARNING을 붙여, 에이전트가 그 뒤에 쌓지 않게 합니다. - 정체 감지 — ComfyUI로의 수동 WebSocket이 실행 중인 프롬프트 / 노드 /
진행률을 추적합니다. 임계값
(
COMFYUI_MCP_STALL_S, 기본값 180초) 을 넘겨 더 이상 나아가지 않는 단계는 에이전트의 다음 턴 앞에 한 줄 STALL/BACKLOG 노트를 붙입니다. - 단계적 취소 —
queue(action:“cancel”)는 중단하고, 작업이 실제로 멈췄는지 확인한 뒤 (COMFYUI_MCP_INTERRUPT_S이내, 기본값 30초)/free로 격상하고 그래도 죽지 않으면 렌더를 WEDGED로 보고합니다 (restart_comfyui제안).clear_pending은 같은 호출에서 대기 중인 작업을 모두 버립니다.
get_image (action:"analyze_color")로 비전 왕복 없이 이미지의 색을 추론할 수 있습니다
(주 팔레트, 평균 + 휘도 통계, 대비 검사).
도구 카테고리
이미지 생성
워크플로우 실행
워크플로우 작성
워크플로우 라이브러리
에셋과 이미지
모델
커스텀 노드
API 노드
설치와 환경
프로세스 제어
기본값, 통계, 스킬
도구 레퍼런스는 실시간 MCP 도구 스키마에서 생성되므로 (
npm run docs:gen)
코드와 어긋나지 않습니다.