문제 해결 - ComfyUI MCP

이 페이지의 모든 항목은 실제 버그 리포트에서 시작되었습니다. 겪고 계신 문제가 여기 없다면 이슈를 등록해 주세요 — 아마 이 페이지에 추가될 것입니다.

`install_custom_node`가 `/v2/manager/queue/task`에서 `405 Method Not Allowed`로 실패함

원인: ComfyUI-Manager에는 두 세대가 존재합니다. /v2/manager/* API는 v4 계열 (pip 패키지 comfyui_manager ≥ 4.x)이며, ComfyUI-Manager가 기본으로 설치하는 출시된 Manager 3.x는 같은 대기열을 다른 라우트로 제공합니다. 해결: comfyui-mcp를 0.24.3 이상으로 업데이트하세요 — 대상별로 Manager 세대를 자동 감지해 두 방식을 모두 지원합니다. Manager를 변경할 필요는 없습니다. 선택 사항이지만 권장 — Manager v4로 업그레이드하면 3.x가 원격으로 할 수 없는 기능(특히 3.x가 화이트리스트로 제한하는 임의 URL 모델 다운로드)을 사용할 수 있습니다:

# in your ComfyUI python environment
pip install -U comfyui_manager
# then remove/disable the old custom_nodes/ComfyUI-Manager clone and restart

RunPod 이미지에는 이미 Manager v4가 포함되어 있습니다. useCmCli: true에 대한 참고: cm-cli 폴백은 Manager의 CLI를 서브프로세스로 실행하므로 로컬 파일시스템이 필요합니다 — 원격/--tunnel 대상에는 사용할 수 없으며, python이 PATH에 없을 때는 COMFYUI_PYTHON이 ComfyUI venv의 인터프리터를 가리키도록 설정해야 합니다. 원격 대상에는 Manager HTTP 경로(기본값)가 적절한 방식입니다.

git URL로 설치한 커스텀 노드가 나타나지 않음

레지스트리 ID로 설치하면 정상 동작하지만, GitHub URL을 직접 사용한 설치는 성공했다고 표시되면서도 팩이 전혀 나타나지 않습니다. 원인: Manager는 임의의 git URL 설치를 고위험으로 간주해, 허용 수준의 보안 등급보다 낮으면 조용히 건너뜁니다(그럼에도 대기열 작업은 “완료”로 표시됩니다). Manager 3.x에는 추가로 전용 allow_git_url_install 설정 플래그가 있습니다. 해결: Manager의 config.ini(ComfyUI 사용자 디렉터리 아래)에서:

[default]
security_level = weak          ; Manager v4: allows git-URL installs
allow_git_url_install = True   ; Manager 3.x: additionally required

이후 ComfyUI를 다시 시작하세요. RunPod 이미지에서는 1.6 이미지부터 이 값이 기본값입니다(COMFY_SECURITY_LEVEL 환경 변수가 이를 덮어쓰며, 부팅할 때마다 값이 다시 적용됩니다). 1.4/1.5 이미지는 이렇게 동작하도록 의도되었지만, 내장된 COMFY_SECURITY_LEVEL=normal- 환경 변수가 부팅 스크립트의 기본값을 덮어썼습니다 — 해당 이미지에서는 파드의 환경 변수에 COMFY_SECURITY_LEVEL=weak를 직접 설정하세요. 이 설정은 본인이 관리하는 머신에서만 완화하세요 — Manager의 설치 안전장치를 제거하는 것이기 때문입니다.

RunPod: 에이전트 패널 탭이 비어 있음 — 파일은 존재하지만 모두 0바이트

ComfyUI에 comfyui-mcp-panel이 표시되지만 사이드바 탭이 전혀 로드되지 않습니다. ls -la /workspace/custom_nodes/comfyui-mcp-panel을 실행하면 모든 파일이 0바이트로 나타납니다. 사용자가 설치한 다른 노드도 같은 방식으로 비어 있을 수 있습니다. 원인: 네트워크 볼륨이 어느 시점에 공간 부족이 된 것입니다(작은 볼륨에서 최초 부팅 시 약 7GB의 스팟체크 모델 복사가 실행되거나, 대용량 모델을 다운로드할 때 흔히 발생합니다). ENOSPC 상태에서도 cp/git은 각 파일을 생성은 하지만 내용은 전혀 쓰지 못합니다 — 볼륨은 계속 유지되므로, 이 빈 껍데기 파일들은 재배포할 때마다 그대로 남습니다. 해결: 볼륨 공간을 확보하거나 늘린 뒤 파드를 다시 시작하세요. 1.6 이미지부터는 부팅 스크립트가 볼륨이 부족하거나 가득 찼을 때 경고를 표시하고, 공간이 부족하면 스팟체크 모델 복사를 건너뛰며, 0바이트 패널을 자동으로 스스로 복구합니다 (GitHub에서 다시 클론하거나, 오프라인이면 이미지에 포함된 시드를 사용합니다). 또한 다른 손상된 노드가 있으면 WARN: custom nodes with 0-byte __init__.py 로그로 이름을 남깁니다 — 이런 노드는 Manager를 통해 다시 설치하세요. <= 1.5 이미지에서는 패널 폴더를 삭제한 뒤 다시 시작하세요: rm -rf /workspace/custom_nodes/comfyui-mcp-panel.

패널에 “브리지(ws://127.0.0.1:9180)에서 대기 중인 에이전트가 없습니다”라는 메시지가 표시됨

오케스트레이터가 실행 중인 머신과 다른 머신의 브라우저에서 ComfyUI를 열고 있는 것입니다. 브리지는 설계상 루프백 전용이며, 브라우저에서의 127.0.0.1은 서버가 아니라 브라우저가 실행 중인 머신을 가리킵니다. 해결 — 브라우저가 있는 머신에서 오케스트레이터를 실행하세요 (이것이 지원되는 구성입니다 — 에이전트는 사용자의 머신에서 실행되며 원격 ComfyUI를 제어합니다):

npx -y comfyui-mcp@latest connect http://<comfyui-host>:8188

그런 다음 패널에서 연결을 클릭하세요. ComfyUI 박스에는 ComfyUI와 패널 커스텀 노드 외에는 아무것도 실행할 필요가 없습니다. https ComfyUI(RunPod 프록시)의 경우 오케스트레이터가 브리지를 보안 wss:// 터널로 자동 업그레이드합니다 — 명령어는 동일합니다. 또는 서버 측에서 오케스트레이터를 실행하세요 (0.24.5 이상) — 에이전트가 ComfyUI 옆에서 상시 실행되고 LAN의 어디서든 브라우저가 연결할 수 있어야 하는 24/7 헤드리스 박스(예: 독립형 Ollama/OpenClaw 서버)에 적합합니다:

# on the SERVER — bind the bridge on the LAN, token-gated (mandatory)
COMFYUI_MCP_BRIDGE_HOST=0.0.0.0 \
COMFYUI_MCP_BRIDGE_TOKEN=<pick-a-long-secret> \
npx -y comfyui-mcp@latest --panel-orchestrator

바로 붙여넣을 수 있는 ws://<server-ip>:9180/?token=…가 출력됩니다 — 이 값을 아무 머신에서나 패널의 설정 → 고급 → 브리지 URL에 입력하고 연결을 클릭하세요. 루프백이 아닌 바인딩은 토큰 없이는 시작 자체가 거부되며, 모든 연결은 WebSocket 업그레이드 시점에 검사됩니다(상수 시간 비교). 이 URL은 비밀번호처럼 다루세요 — 이를 가진 사람은 누구나 에이전트를 조작할 수 있습니다.

새 릴리스가 나왔는데 여전히 예전 동작이 보임

npx는 패키지를 적극적으로 캐싱합니다 — npx -y comfyui-mcp@latest가 ~/.npm/_npx에 있는 몇 주 전 빌드를 그대로 제공할 수 있습니다.

# clear it, then relaunch
npx clear-npx-cache
# or on Windows:
#   Remove-Item -Recurse -Force "$env:LOCALAPPDATA\npm-cache\_npx"

패널 커스텀 노드도 확인하세요: 이전 설치에서 남은 것이 네트워크 볼륨(RunPod의 /workspace)에 있다면, 그 사본이 이미지의 자동 업데이트본을 가려버립니다. git -C <panel-dir> fetch && git -C <panel-dir> reset --hard origin/main을 실행하거나 ComfyUI-Manager에서 comfyui-agent-panel을 다시 설치한 뒤, ComfyUI를 재시작하고 브라우저 탭을 강력 새로고침하세요(Ctrl+Shift+R).

포트 포워딩된 원격 ComfyUI가 로컬로 잘못 감지됨 (dstack, SSH 터널)

localhost:8188으로 접근 가능한 원격 ComfyUI(dstack, ssh -L, kubectl port-forward)는 루프백 휴리스틱을 오작동시킵니다: comfyui-mcp가 로컬 설치라고 판단해, ComfyUI가 실제로 없는 파일시스템에 대해 로컬 전용 도구를 활성화합니다. 해결 (0.24.1 이상): --force-remote(또는 COMFYUI_MCP_FORCE_REMOTE=1)를 전달하세요:

npx -y comfyui-mcp@latest connect http://localhost:8188 --force-remote

원격 대상의 생성 기록은 ~/.comfyui-mcp/instances/<host_port>/에 저장됩니다 (COMFYUI_MCP_DATA_DIR로 재정의 가능).

Docker: HTTP 모드에서 컨테이너가 즉시 종료됨

인증 없이 루프백이 아닌 호스트에 바인딩하면 설계상 무조건 실패합니다 (0.0.0.0에 열린 /mcp 엔드포인트가 노출되기 때문입니다). 토큰을 전달하거나, 명시적으로 이 검사를 해제하세요:

docker run --rm -p 9100:9100 -e COMFYUI_MCP_HTTP_TOKEN=changeme comfyui-mcp \
  --http --host 0.0.0.0 --port 9100
# or (trusted networks only):
#   ... --http --host 0.0.0.0 --port 9100 --allow-unauthenticated-non-loopback

stdio 모드(기본값이며 MCP 클라이언트가 사용하는 방식)에는 이런 설정이 전혀 필요 없습니다.

에이전트가 도구를 전혀 호출하지 않음 — 오류 없이 그냥 말만 함

워크플로우를 읽는 대신 설명만 하거나, 스크립트를 대신 작성해 주겠다고 제안합니다. 아무것도 실패하지 않았기 때문에 오류는 나타나지 않습니다: 도구 목록이 클라이언트에 전달되지 않았거나, 클라이언트가 호출을 막고 있거나, 해당 기능이 한 번도 언급되지 않은 이름으로 존재하는 경우 중 하나입니다. 이 세 가지는 겉으로는 똑같아 보이지만 해결 방법은 정반대이므로, 추측하기보다는 확인하는 편이 낫습니다. 에이전트에게 두 가지 질문을 던져보면 구분할 수 있습니다 — 아무 말도 하지 않을 때를 참고하세요. 클라이언트 측 권한 차단은 이 서버에 전혀 도달하지 않으므로, 아래 로그 어디에도 나타나지 않는다는 점을 유의하세요.

로컬 모델: 도구 호출이 실패하거나 모델이 도구를 “인식하지 못함”

가장 먼저 시도할 것: 자체 파인튜닝 모델을 사용하세요 — ollama pull artokun/gemma4-comfyui-mcp:e4b(패널의 Ollama 기본값입니다). comfyui-mcp 도구 모음 자체로 학습된 Gemma 4로, “잘못된 도구 선택 / 잘못된 형식의 인자” 실패 대부분을 기본 상태에서 없애줍니다(VRAM 약 2GB면 :e2b, 약 8GB면 :12b — 모든 단계가 아레나에서 기본 베이스 모델을 능가하며, :e4b가 최적점입니다).
gemma3는 Ollama에서 네이티브 도구 호출을 지원하지 않습니다 — 지원되지 않으니, 위의 자체 파인튜닝 모델이나 기본 gemma4(e4b 이상), qwen3, llama3.1+을 사용하세요.
소형 모델에는 컴팩트 도구 모드를 켜세요 — 이는 기본값이 아니므로, 서버를 시작할 때 --compact(또는 COMFYUI_MCP_TOOL_MODE=compact)를 지정해야 합니다. 켜지 않으면 전체 스키마가 작은 컨텍스트를 넘쳐, 모델이 도구 이름을 지어내기 시작합니다.
콜드 상태에서 모델을 불러올 때는 첫 토큰이 나오기까지 30초 이상 걸릴 수 있습니다 — 패널의 워치독은 이를 감안하지만, 요청이 즉시 실패한다면 대개 해당 모델 태그를 아직 받지 않은 것입니다(ollama pull <tag>).
모든 요청이 갑자기 실패함 / 11434 포트에서 연결 거부됨 — Ollama 앱/데몬이 실행되고 있지 않은 것입니다. 트레이 앱을 종료하면 API도 함께 죽는데, 에이전트가 실행되는 도중에 실수로 이렇게 하기 쉽습니다(패널은 로컬 백엔드가 사용 중이라는 경고를 표시하지 않습니다). 앱을 다시 실행하거나(또는 ollama serve) 재연결하세요 — 세션은 이어지며 패널을 재시작할 필요는 없습니다.

로그를 확인할 위치

오케스트레이터: connect / --panel-orchestrator를 실행 중인 터미널입니다.
ComfyUI 측: get_system_stats (action:"logs") MCP 도구, 또는 RunPod에서는 파드의 로그 스트림입니다.
패널 JS: 브라우저 devtools 콘솔입니다(브리지 클라이언트가 연결/재연결 전환을 로그로 남깁니다).
한 번의 호출로 확인하는 상태: get_system_stats (action:"health") 도구가 버전/GPU/VRAM/대기열/모델 디렉터리/최근 오류를 종합해 보여줍니다.

​install_custom_node가 /v2/manager/queue/task에서 405 Method Not Allowed로 실패함

​git URL로 설치한 커스텀 노드가 나타나지 않음

​RunPod: 에이전트 패널 탭이 비어 있음 — 파일은 존재하지만 모두 0바이트

​패널에 “브리지(ws://127.0.0.1:9180)에서 대기 중인 에이전트가 없습니다”라는 메시지가 표시됨

​새 릴리스가 나왔는데 여전히 예전 동작이 보임

​포트 포워딩된 원격 ComfyUI가 로컬로 잘못 감지됨 (dstack, SSH 터널)

​Docker: HTTP 모드에서 컨테이너가 즉시 종료됨

​에이전트가 도구를 전혀 호출하지 않음 — 오류 없이 그냥 말만 함

​로컬 모델: 도구 호출이 실패하거나 모델이 도구를 “인식하지 못함”

​로그를 확인할 위치