메인 콘텐츠로 건너뛰기
초기 미리보기. comfy-local-mcp는 초기 개념 증명(proof-of-concept)입니다. 핵심 루프(server_info → run_workflow → fetch_outputs)는 실제 로컬 ComfyUI에 대해 종단 간 검증되었지만, 도구와 동작은 변경될 수 있습니다.
comfy-local-mcp는 Comfy의 공식 로컬 MCP 서버입니다: AI 에이전트(Claude Code, Claude Desktop, Cursor 및 기타 MCP 클라이언트)에서 로컬 ComfyUI 설치를 구동하는 공식적인 방법입니다. 이는 comfy-cli의 간단한 래퍼입니다: 각 도구는 comfy 명령을 호출하므로, comfy-cli가 엔진이며 Comfy Cloud MCP와 코드를 공유하지 않습니다. 클라우드 및 파트너 서버와 달리, 사용자 자신의 머신에서 실행되는 ComfyUI와 통신하므로 워크플로를 실행하고 설치에 실제로 있는 노드, 커스텀 노드 및 모델을 검사할 수 있습니다.

​
요구 사항

  • Python 3.10+
  • PATH에 **comfy-cli**가 있어야 합니다 (pip install comfy-cli). 모든 도구가 기반으로 하는 엔진입니다.
  • ComfyUI 워크스페이스: 없으면 comfy install로 생성합니다 (기존 체크아웃은 comfy set-default <path>로 설정 가능).
  • 실행 중인 ComfyUI: 도구 사용 이전에 comfy launch로 시작합니다. 여기서는 ComfyUI를 암시적으로 실행하지 않습니다.

​
설치

저장소를 체크아웃한 후: 
pip install .        # 또는 작업 복사본의 경우 `pip install -e .`
그러면 PATH에 comfy-local-mcp 콘솔 스크립트가 생깁니다. 이 명령은 MCP 서버입니다 (stdio를 통해 MCP와 통신함). 아래에서 AI 클라이언트를 이 서버에 연결하세요.
COMFY_BIN (선택 사항). MCP 클라이언트는 자체 환경으로 서버를 실행하며, 이 환경에는 일반적으로 셸의 PATH가 포함되지 않습니다. comfy가 가상 환경이나 비표준 위치에 있는 경우 COMFY_BIN을 해당 절대 경로(예: /path/to/venv/bin/comfy)로 설정하세요. 아래의 모든 클라이언트 예제에서 해당 위치를 보여줍니다. 클라이언트가 서버를 실행하는 환경에 이미 comfy가 있다면 생략하세요.

​
AI 클라이언트 설정하기

모든 클라이언트는 동일한 MCP stdio 계약을 따릅니다: comfy-local-mcp 명령을 서버로 실행하세요. 클라이언트를 선택하세요.

​
Claude Code

한 번의 명령으로 서버를 등록합니다: 
claude mcp add comfy-local -e COMFY_BIN=/path/to/venv/bin/comfy -- comfy-local-mcp
또는 프로젝트 루트에 .mcp.json 파일로 체크인합니다: 
{
  "mcpServers": {
    "comfy-local": {
      "command": "comfy-local-mcp",
      "env": { "COMFY_BIN": "/path/to/venv/bin/comfy" }
    }
  }
}

​
Claude Desktop

claude_desktop_config.json을 편집하세요 (설정 → 개발자 → 구성 편집; macOS에서는 ~/Library/Application Support/Claude/claude_desktop_config.json에 위치합니다), 서버를 추가한 후 Claude Desktop을 재시작하세요: 
{
  "mcpServers": {
    "comfy-local": {
      "command": "comfy-local-mcp",
      "env": { "COMFY_BIN": "/path/to/venv/bin/comfy" }
    }
  }
}

​
Cursor

서버를 ~/.cursor/mcp.json (전역) 또는 .cursor/mcp.json (프로젝트별)에 추가하세요: 
{
  "mcpServers": {
    "comfy-local": {
      "command": "comfy-local-mcp",
      "env": { "COMFY_BIN": "/path/to/venv/bin/comfy" }
    }
  }
}

​
빠른 시작

생성된 이미지까지 제로부터:
1

설치 구성

pip install comfy-cli     # 엔진
comfy install             # ComfyUI 워크스페이스 생성 (이미 있으면 건너뛰기)
pip install .             # 이 MCP 서버 → `comfy-local-mcp` 명령
2

ComfyUI 실행하고 계속 실행 상태 유지

comfy launch
3

클라이언트에 서버 추가

위에서 클라이언트에 맞는 스니펫을 사용한 후, 클라이언트를 재시작하거나 다시 로드하면 도구가 나타납니다.
4

에이전트에게 워크플로 실행 요청

예를 들어:
“내 로컬 ComfyUI가 실행 중인지 확인한 다음 ~/workflows/txt2img.json의 워크플로를 실행하고 이미지를 보여줘.”
내부적으로 에이전트는 server_info를 호출하여 ComfyUI가 작동 중인지 확인하고, run_workflow를 호출하여 워크플로 JSON을 실행하며, fetch_outputs를 호출하여 결과를 수집합니다.

​
도구

각 도구는 comfy-cli 명령에 매핑되며, --where local로 실행됩니다. 주요 기능:
도구용도
server_info()로컬 ComfyUI가 실행 중인지, 위치, 워크스페이스를 확인합니다. 먼저 호출하세요.
run_workflow(workflow_path, wait=True)워크플로 JSON을 실행합니다. wait=False는 비동기로 제출하고 prompt_id를 반환합니다.
job_status / wait_for_job / watch_job제출된 작업을 폴링, 대기 또는 스트리밍합니다.
fetch_outputs(prompt_id, out_dir)완료된 작업의 출력을 out_dir로 복사합니다.
launch_comfyui / stop_comfyui로컬 ComfyUI를 시작하거나 중지합니다.
search_templates / fetch_template내장 템플릿을 찾아 실행 가능한 워크플로 JSON으로 작성합니다.
search_nodes / get_node / list_nodes실행 중인 로컬 설치의 노드 클래스를 검사합니다 (커스텀 노드 포함).
search_models디스크의 모델 파일을 나열합니다.
validate_workflow느린 실행 이전에 실행 중인 object_info를 기준으로 워크플로를 사전 점검합니다.
노드 인트로스펙션과 모델 검색은 실행 중인 설치(커스텀 노드 포함)를 읽습니다. 이것이 로컬이 클라우드 MCP와 차별화되는 점입니다. 전체 도구 목록과 참조는 저장소를 참조하세요.

​
관련