comfyui-local-mcp

MCP 클라이언트(Hermes, Claude Code, Cursor, 모든 MCP 에이전트)에서 로컬 ComfyUI를 구동하세요 — Apple Silicon(MLX + MPS) 용으로 제작된 FLUX.2 Klein 텍스트-이미지 워크플로우가 포함되어 있습니다.

제작 및 테스트 환경: Mac mini M4 · 24GB 통합 메모리 · macOS 26 · ComfyUI 0.33 · mflux 0.19

기능

• 🖼️ generate_image — 자동 모델 탐색을 통한 텍스트-이미지 생성:

  • mflux:<name> — FLUX.2 Klein 4B / 9B, 4비트 MLX (빠름, 낮은 메모리)

  • bf16 — ComfyUI 네이티브 bf16 (MPS, 최고 품질)

  • auto — 최적의 모델을 자동 선택 (9B 우선)

• 📦 list_models — 설치된 모델 목록 표시 (models/mflux/ 자동 스캔, 코드 변경 없이 모델 추가 가능)

• 🗂️ list_outputs — 최근 생성된 이미지 목록

• 🩺 system_status — 한 번의 호출로 진단 (ComfyUI 서비스, 모델, 디스크)

Related MCP server: comfyui-mcp

빠른 시작

# 1. Install the server files into your ComfyUI + register the hermes MCP
./install.sh                # optional; also fine to just copy files

# 2. Register the MCP server manually (or via install.sh) — e.g. in ~/.hermes/config.yaml:
#   mcp_servers:
#     comfyui-local:
#       command: /path/to/python-with-mcp
#       args: [/path/to/comfyui-local-mcp/mcp_comfyui_server.py]
#       enabled: true

# 3. Test the server (stdio MCP handshake)
python mcp_comfyui_server.py

# 4. Ask your agent: "generate an image of ..." or "check my ComfyUI status"

요구 사항

• Apple Silicon이 탑재된 macOS (MLX / Metal)

• 로컬에서 실행 중인 ComfyUI (기본값 127.0.0.1:8188)

• mcp 패키지가 설치된 Python 환경 (서버 자체는 stdlib + mcp만 필요)

• 선택 사항: mflux + MLX 경로용 ComfyUI-mflux-AnyModel 커스텀 노드

• 선택 사항: bf16 경로용 FLUX.2 Klein bf16 가중치 + Qwen3-4B 텍스트 인코더

모델 설정 (Apple Silicon, 24GB 친화적)

HF 캐시를 사용하여 mflux MLX 모델을 다운로드하고 models/mflux/에 심볼릭 링크로 연결하세요 (HF 캐싱 / 심볼릭 링크 참조) — 서버가 자동으로 발견합니다.

Apple Silicon 참고 사항

• fp8 가중치는 MPS에서 작동하지 않습니다 — 먼저 bf16으로 변환하세요 (CPU 측 역양자화). flux-2-klein-4b-bf16.safetensors는 공식 fp8 체크포인트의 bf16 변환본입니다.

• 일부 네트워크에서 HF 다운로드가 중단될 수 있습니다 — export HF_HUB_DISABLE_XET=1로 해결하세요.

• 성능 (M4 10코어 GPU, 1024×1024): 4B-4bit ~12.7초/스텝 (최대 ~11GB), bf16 ~12.1초/스텝 (최대 ~15GB).

HF 캐싱 및 심볼릭 링크

HuggingFace snapshot_download는 실제 데이터를 ~/.cache/huggingface/hub/models--<org>--<name>/blobs/에 저장하고 snapshots/<rev>/ 아래에 심볼릭 링크를 노출합니다. 이 프로젝트는 models/mflux/<Model-Name>/에 해당 스냅샷을 가리키는 심볼릭 링크를 유지합니다 — 디스크 사용량 중복 없음, list_models가 자동으로 인식합니다.

문제 해결

./check_system.sh        # one-shot diagnosis
tail -50 ~/comfyui_run.log

• ComfyUI가 응답하지 않나요? 127.0.0.1:8188에서 실행 중인지 확인하세요 (먼저 중단된 인스턴스를 종료).

• list_models에 모델이 없나요? transformer/ 하위 디렉터리와 함께 models/mflux/에 심볼릭 링크(또는 복사)하세요.

• 에이전트에서 MCP가 보이지 않나요? config.yaml을 편집한 후 에이전트 세션을 다시 시작하세요.

라이선스

MIT