> ## Documentation Index
> Fetch the complete documentation index at: https://docs.comfy.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Comfy Local MCP

> 자신의 로컬 ComfyUI를 AI 에이전트(Claude Code, Claude Desktop, Cursor)에서 구동하세요. 공식 comfy-local-mcp 서버를 사용하여 워크플로를 실행하고, 출력을 수집하며, 실제 설치된 노드와 모델을 검사할 수 있습니다.

<Warning>
  **초기 미리보기.** `comfy-local-mcp`는 초기 개념 증명(proof-of-concept)입니다. 핵심 루프(`server_info → run_workflow → fetch_outputs`)는 실제 로컬 ComfyUI에 대해 종단 간 검증되었지만, 도구와 동작은 변경될 수 있습니다.
</Warning>

[**comfy-local-mcp**](https://github.com/Comfy-Org/comfy-local-mcp)는 Comfy의 **공식 로컬 MCP 서버**입니다: AI 에이전트(Claude Code, Claude Desktop, Cursor 및 기타 MCP 클라이언트)에서 **로컬** ComfyUI 설치를 구동하는 공식적인 방법입니다. 이는 [comfy-cli](https://github.com/Comfy-Org/comfy-cli)의 간단한 래퍼입니다: 각 도구는 `comfy` 명령을 호출하므로, `comfy-cli`가 엔진이며 [Comfy Cloud MCP](/ko/agent-tools/cloud)와 코드를 공유하지 않습니다.

클라우드 및 파트너 서버와 달리, **사용자 자신의 머신**에서 실행되는 ComfyUI와 통신하므로 워크플로를 실행하고 설치에 실제로 있는 노드, 커스텀 노드 및 모델을 검사할 수 있습니다.

***

## 요구 사항

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

***

## 설치

[저장소](https://github.com/Comfy-Org/comfy-local-mcp)를 체크아웃한 후:

```bash theme={null}
pip install .        # 또는 작업 복사본의 경우 `pip install -e .`
```

그러면 `PATH`에 `comfy-local-mcp` 콘솔 스크립트가 생깁니다. 이 명령은 MCP 서버입니다 (stdio를 통해 MCP와 통신함). 아래에서 AI 클라이언트를 이 서버에 연결하세요.

<Note>
  **`COMFY_BIN` (선택 사항).** MCP 클라이언트는 자체 환경으로 서버를 실행하며, 이 환경에는 일반적으로 셸의 `PATH`가 **포함되지 않습니다**. `comfy`가 가상 환경이나 비표준 위치에 있는 경우 `COMFY_BIN`을 해당 절대 경로(예: `/path/to/venv/bin/comfy`)로 설정하세요. 아래의 모든 클라이언트 예제에서 해당 위치를 보여줍니다. 클라이언트가 서버를 실행하는 환경에 이미 `comfy`가 있다면 생략하세요.
</Note>

***

## AI 클라이언트 설정하기

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

### Claude Code

한 번의 명령으로 서버를 등록합니다:

```bash theme={null}
claude mcp add comfy-local -e COMFY_BIN=/path/to/venv/bin/comfy -- comfy-local-mcp
```

또는 프로젝트 루트에 `.mcp.json` 파일로 체크인합니다:

```json theme={null}
{
  "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을 재시작하세요:

```json theme={null}
{
  "mcpServers": {
    "comfy-local": {
      "command": "comfy-local-mcp",
      "env": { "COMFY_BIN": "/path/to/venv/bin/comfy" }
    }
  }
}
```

### Cursor

서버를 `~/.cursor/mcp.json` (전역) 또는 `.cursor/mcp.json` (프로젝트별)에 추가하세요:

```json theme={null}
{
  "mcpServers": {
    "comfy-local": {
      "command": "comfy-local-mcp",
      "env": { "COMFY_BIN": "/path/to/venv/bin/comfy" }
    }
  }
}
```

***

## 빠른 시작

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

<Steps>
  <Step title="설치 구성">
    ```bash theme={null}
    pip install comfy-cli     # 엔진
    comfy install             # ComfyUI 워크스페이스 생성 (이미 있으면 건너뛰기)
    pip install .             # 이 MCP 서버 → `comfy-local-mcp` 명령
    ```
  </Step>

  <Step title="ComfyUI 실행하고 계속 실행 상태 유지">
    ```bash theme={null}
    comfy launch
    ```
  </Step>

  <Step title="클라이언트에 서버 추가">
    위에서 클라이언트에 맞는 스니펫을 사용한 후, 클라이언트를 재시작하거나 다시 로드하면 도구가 나타납니다.
  </Step>

  <Step title="에이전트에게 워크플로 실행 요청">
    예를 들어:

    > "내 로컬 ComfyUI가 실행 중인지 확인한 다음 `~/workflows/txt2img.json`의 워크플로를 실행하고 이미지를 보여줘."

    내부적으로 에이전트는 `server_info`를 호출하여 ComfyUI가 작동 중인지 확인하고, `run_workflow`를 호출하여 워크플로 JSON을 실행하며, `fetch_outputs`를 호출하여 결과를 수집합니다.
  </Step>
</Steps>

***

## 도구

각 도구는 `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와 차별화되는 점입니다. 전체 도구 목록과 참조는 [저장소](https://github.com/Comfy-Org/comfy-local-mcp)를 참조하세요.

***

## 관련

* [Comfy Cloud MCP](/ko/agent-tools/cloud): 호스팅된 MCP 서버, 로컬 설치나 GPU 불필요
* [Comfy Partner MCP](/ko/agent-tools/partner-mcp): 30개 이상의 파트너 제공자를 위한 로컬 서버 (Comfy API 사용)
* [Comfy CLI](/ko/agent-tools/comfy-cli): 터미널에서 로컬 ComfyUI 및 파트너 생성 구동
* [comfy-local-mcp on GitHub](https://github.com/Comfy-Org/comfy-local-mcp): 소스, 설치, 도구 참조