comfyui-mcp

ComfyUI용 MCP 서버입니다. MCP 호환 클라이언트를 사용하여 자연어 프롬프트로 이미지를 생성하세요.

MCP Server Series의 일부입니다.

상태

v0.2 — 핵심 도구, 업스케일, 이미지 프록시 및 공용 URL 지원. 도구: generate_image, generate_variations, generate_with_workflow, refine_image, upscale_image, list_models, list_workflows, upload_image. 다음 계획은 로드맵을 참조하세요.

설치

npx (설치 불필요)

npx @miller-joe/comfyui-mcp --comfyui-url http://your-comfyui-host:8188

npm

npm install -g @miller-joe/comfyui-mcp
comfyui-mcp --comfyui-url http://your-comfyui-host:8188

Docker

docker run -p 9100:9100 \
  -e COMFYUI_URL=http://your-comfyui-host:8188 \
  ghcr.io/miller-joe/comfyui-mcp:latest

MCP 클라이언트 연결

예시 — Claude Code:

claude mcp add --transport http comfyui http://localhost:9100/mcp

또는 스트리밍 가능한 HTTP 엔드포인트를 MCP 게이트웨이(예: MetaMCP)에 등록하여 다른 서버와 통합할 수 있습니다.

구성

모든 옵션은 CLI 플래그 또는 환경 변수를 통해 설정할 수 있습니다:

클라이언트에 반환되는 이미지 URL

생성 도구는 <comfyui-public-url>/view?filename=…와 같은 이미지 URL을 반환합니다. --comfyui-public-url이 설정되지 않은 경우, 내부 --comfyui-url 값이 사용됩니다.

또한 서버는 프록시 엔드포인트를 노출합니다: GET /images/<filename>?subfolder=&type=output은 이미지 바이트를 MCP 서버를 통해 스트리밍합니다. 클라이언트가 MCP 서버에는 접근할 수 있지만 ComfyUI에는 직접 접근할 수 없을 때 유용합니다.

기본 체크포인트는 ComfyUI models/checkpoints/ 디렉토리에 설치된 파일과 일치해야 합니다. COMFYUI_DEFAULT_CKPT를 통해 재정의하거나 도구 인수로 checkpoint를 전달하세요.

도구

generate_image

ComfyUI의 기본 txt2img 워크플로우를 사용하여 텍스트 프롬프트에서 이미지를 생성합니다.

매개변수: prompt (필수), negative_prompt, width, height, steps, cfg, seed, checkpoint.

generate_variations

시드를 변경하여 동일한 프롬프트의 여러 변형을 생성합니다. 모든 이미지를 한 번에 반환합니다.

매개변수: prompt (필수), count (2–16, 기본값 4), 그리고 generate_image와 동일한 생성 매개변수 (단, seed 대신 base_seed 사용).

generate_with_workflow

임의의 ComfyUI 워크플로우 JSON(전체 노드 그래프)을 제출하고 결과 이미지 URL을 반환합니다. 사용자 정의 워크플로우(ControlNet, 업스케일링 또는 ComfyUI의 **Save (API Format)**에서 내보낸 모든 것)에 사용하세요.

매개변수: workflow (객체) — 전체 노드 그래프.

refine_image

소스 이미지에서 img2img를 실행합니다: 소스 URL을 가져와 ComfyUI에 업로드하고, 새 프롬프트에 따라 디노이징 패스를 실행합니다. denoise 값을 낮추면 원본이 더 많이 보존되고, 높이면 프롬프트에 더 많은 자유도가 부여됩니다.

매개변수: prompt, source_image_url (필수), denoise (0–1, 기본값 0.5), 그리고 표준 생성 매개변수.

list_models

ComfyUI 인스턴스에서 사용 가능한 체크포인트, LoRA, 샘플러 또는 스케줄러를 나열합니다.

매개변수: kind — checkpoints (기본값), loras, samplers, schedulers 중 하나.

list_workflows

이 서버와 함께 제공되는 내장 워크플로우 템플릿(현재 txt2img, img2img)을 나열합니다.

upload_image

img2img, ControlNet 또는 IP-Adapter 워크플로우에서 사용할 참조 이미지를 ComfyUI에 업로드합니다.

매개변수: source_url 또는 image_base64 (하나 필수), filename (선택 사항), overwrite (기본값 false).

반환값: 저장된 파일명. 워크플로우 노드에서 LoadImage 등의 입력으로 사용할 수 있습니다.

generate_with_controlnet

ControlNet 전처리 이미지(포즈 스켈레톤, 깊이 맵, Canny 엣지, 노멀 맵 등)와 텍스트 프롬프트로 조건이 지정된 이미지를 생성합니다.

매개변수: prompt, control_image_url (전처리된 조건 이미지 — 이 도구는 전처리기를 실행하지 않음), controlnet_model (models/controlnet/의 파일명), strength (0–2, 기본값 1), start_percent / end_percent (0–1, 샘플링 중 CN이 활성화되는 시점), 그리고 표준 생성 매개변수.

ComfyUI models/controlnet/ 디렉토리에 ControlNet 모델이 설치되어 있어야 합니다.

generate_with_ip_adapter

IP-Adapter를 통해 참조 이미지를 시각적/스타일/주제 가이드로 사용하여 이미지를 생성합니다.

매개변수: prompt, reference_image_url, preset (예: "STANDARD (medium strength)", "PLUS FACE (portraits)", "VIT-G (medium strength)"), weight (0–3, 기본값 1), start_at / end_at (0–1), 그리고 표준 생성 매개변수.

ComfyUI-IPAdapter-plus 커스텀 노드 팩과 프리셋에 맞는 IPAdapter 가중치 및 CLIP Vision 모델이 필요합니다.

워크플로우 템플릿 레지스트리

복잡한 워크플로우 JSON을 한 번 저장하고 나중에 이름으로 실행하세요. 템플릿은 --templates-dir 아래 디스크에 저장되므로(기본값 ~/.config/comfyui-mcp/templates/<name>.json) 재시작 후에도 유지되며 MCP 클라이언트 간에 이식 가능합니다.

템플릿 이름은 영숫자로 시작해야 하며 a-z, A-Z, 0-9, -, _를 포함할 수 있습니다. 최대 64자.

반환 형식

모든 생성 도구는 ComfyUI 인스턴스에서 직접 제공하는 이미지 URL(http://<comfyui>/view?filename=…)을 반환합니다. 이 URL은 이미지 URL을 허용하는 모든 클라이언트에 바로 전달할 수 있습니다.

아키텍처

┌────────────────┐     ┌──────────────────┐     ┌──────────────┐
│  MCP client    │────▶│  comfyui-mcp     │────▶│  ComfyUI     │
│  (Claude, etc.)│◀────│  (this server)   │◀────│  instance    │
└────────────────┘     └──────────────────┘     └──────────────┘
     streamable HTTP        HTTP REST + poll

서버는 상태를 저장하지 않습니다. 단일 MCP 요청 → ComfyUI에 워크플로우 제출 → 완료될 때까지 /history/{id} 폴링 → 이미지 URL 반환.

개발

git clone https://github.com/miller-joe/comfyui-mcp
cd comfyui-mcp
npm install
npm run dev       # hot-reload via tsx watch
npm run build     # compile TS to dist/
npm run typecheck # strict type checking

Node 20+가 필요합니다.

로드맵

• [x] generate_image — 기본 워크플로우를 사용한 텍스트-이미지 변환

• [x] generate_with_workflow — 임의의 워크플로우 제출

• [x] list_models / list_workflows

• [x] upload_image — img2img / ControlNet / IP-Adapter용 참조 이미지

• [x] generate_variations — 프롬프트의 배치 변형

• [x] refine_image — 소스 URL에서 img2img 리파인

• [x] upscale_image — ESRGAN/SwinIR 스타일 모델 업스케일

• [x] ComfyUI에 접근할 수 없는 클라이언트를 위한 이미지 프록시 엔드포인트 (/images/<filename>)

• [x] 외부에서 올바른 이미지 URL을 위한 구성 가능한 공용 URL

• [x] 워크플로우 템플릿 레지스트리: save_workflow_template, list_workflow_templates, get_workflow_template, delete_workflow_template, run_workflow_template

• [x] ControlNet 워크플로우 도우미: generate_with_controlnet (ComfyUI 측에 ControlNet 모델 필요)

• [x] IP-Adapter 워크플로우 도우미: generate_with_ip_adapter (ComfyUI-IPAdapter-plus 팩 필요)

• [ ] 장시간 생성 작업을 위한 WebSocket 진행 상황 이벤트

라이선스

MIT © Joe Miller

지원

이 도구가 시간을 절약해 준다면 개발 지원을 고려해 보세요:

모든 기여는 MCP Server Series의 유지 관리, 문서화 및 다음 릴리스를 지원합니다.