> ## Documentation Index
> Fetch the complete documentation index at: https://dripart-chore-sync-comfy-api-v2-spec-462120c.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Comfy MCP

> Comfy Cloud GPU 또는 자신의 컴퓨터에서 ComfyUI에 AI 에이전트를 연결하세요. 이미지, 비디오, 오디오, 3D를 생성하고, 모델, 노드, 템플릿을 검색하며, 실제 워크플로를 실행할 수 있습니다.

<Info>
  **공개 베타.** Comfy MCP는 현재 공개 베타 상태입니다. API, 도구, 동작은 개선 과정에서 변경될 수 있습니다. 문제를 신고하거나 제안을 공유하려면 [피드백](#피드백)을 참조하세요.
</Info>

## 개요

**Comfy MCP**는 [Model Context Protocol](https://modelcontextprotocol.io)을 통해 AI 에이전트를 ComfyUI에 연결합니다. 연결이 완료되면 이미지, 비디오, 오디오, 3D를 생성하고 모델, 노드, 템플릿을 검색하며, 에이전트와의 채팅에서 실제 ComfyUI 워크플로를 실행할 수 있습니다.

두 가지 연결을 제공합니다. **Comfy Cloud** 연결과 **로컬 ComfyUI** 연결이며, 로컬 연결은 완전한 오픈소스입니다.

<Tip>
  **아래 내용에서 막히는 부분이 있다면? 가장 좋은 방법은 이 페이지를 에이전트에게 건네고 도움을 요청하는 것입니다.**
</Tip>

### 어떤 연결을 선택해야 하나요?

**새로운 사용자라면 클라우드 연결로 시작하는 것을 권장합니다.** 가장 간단한 설정입니다. claude.ai, ChatGPT 또는 Claude Desktop 채팅 앱을 사용 중이라면 클라우드 연결이 더 호환되는 선택입니다.

**이미 ComfyUI를 로컬에서 실행하거나 자체 배포 환경에서 운영 중이거나, Claude Code, Cursor, Codex 같은 코딩 에이전트에서 주로 작업한다면** **로컬** 연결로 시작하세요.

<Info>
  **Mac 사용자의 경우, 오픈소스 모델을 실행할 계획이라면 클라우드 연결을 권장합니다.** 현재의 오픈웨이트 모델(예: MiniMax H3, LTX-2.3의 로컬 버전)은 크기가 커서 Apple GPU에서 실용적인 속도로 실행되지 않습니다.
</Info>

두 연결을 동시에 실행하는 것은 일반적이며, 대부분의 클라이언트는 두 개의 MCP 서버를 문제없이 호스팅합니다. 동일한 Comfy 계정에 로그인하지만 **별도로** 로그인해야 합니다. 하나의 로그인으로 다른 연결을 포함하지 않습니다.

## Comfy Cloud MCP 연결

에이전트를 **Comfy Cloud** 계정에 연결하는 호스팅 연결입니다. 설치할 필요가 없으며, 워크플로는 Comfy Cloud GPU에서 실행됩니다. Comfy Cloud에 대해 더 알아보려면 [Comfy Cloud](/ko/get_started/cloud)를 참조하세요.

### 클라우드 연결 설정

<Info>
  연결 전에 [Comfy Cloud](https://cloud.comfy.org) 계정이 필요합니다. 아직 계정이 없다면 [가입하기](https://cloud.comfy.org)를 클릭하세요. 신규 사용자는 **5회 무료 실행**을 사용해 볼 수 있습니다. 설정 중 OAuth 로그인은 Comfy 계정을 사용합니다.
</Info>

Comfy Cloud MCP는 다음 주소에서 실행됩니다:

```
https://cloud.comfy.org/mcp
```

클라이언트를 선택하세요:

<Tabs>
  <Tab title="Claude Desktop">
    Claude Desktop은 UI를 통해 Comfy Cloud를 **사용자 정의 커넥터**로 추가한 다음 OAuth 로그인을 실행합니다.

    <video controls className="w-full aspect-video rounded-xl" src="https://mintcdn.com/dripart-chore-sync-comfy-api-v2-spec-462120c/LqynrgyB_KXghPT7/images/agent_tools/Claude_desktop.mp4?fit=max&auto=format&n=LqynrgyB_KXghPT7&q=85&s=dcb6d6c674957b1604ffb0a059c5f9de" data-path="images/agent_tools/Claude_desktop.mp4" />

    <Steps>
      <Step title="Customize 열기">
        사이드바에서 **Customize**(라벨 **1**)를 클릭하세요.

        <img src="https://mintcdn.com/dripart-chore-sync-comfy-api-v2-spec-462120c/LqynrgyB_KXghPT7/images/agent_tools/claude_desktop_mcp_setup_step1.png?fit=max&auto=format&n=LqynrgyB_KXghPT7&q=85&s=253eeaa5582a6a986a81ae8a0a34f671" alt="Claude Desktop — open Customize" width="712" height="842" data-path="images/agent_tools/claude_desktop_mcp_setup_step1.png" />
      </Step>

      <Step title="Connectors 열기">
        **Connectors**(라벨 **2**)를 클릭하세요.

        <img src="https://mintcdn.com/dripart-chore-sync-comfy-api-v2-spec-462120c/LqynrgyB_KXghPT7/images/agent_tools/claude_desktop_mcp_setup_step2.png?fit=max&auto=format&n=LqynrgyB_KXghPT7&q=85&s=ac0eb966d53e1096f61f2214f7c16910" alt="Claude Desktop — open Connectors" width="856" height="811" data-path="images/agent_tools/claude_desktop_mcp_setup_step2.png" />
      </Step>

      <Step title="사용자 정의 커넥터 추가">
        1. Connectors 헤더에서 **+** 버튼(라벨 **3**)을 클릭하세요.
        2. **Add custom connector**(라벨 **4**)를 선택하세요.

                   <img src="https://mintcdn.com/dripart-chore-sync-comfy-api-v2-spec-462120c/LqynrgyB_KXghPT7/images/agent_tools/claude_desktop_mcp_setup_step3.png?fit=max&auto=format&n=LqynrgyB_KXghPT7&q=85&s=d9532f78a9d3f2f3372e3c72b8417154" alt="Claude Desktop — add custom connector" width="1314" height="792" data-path="images/agent_tools/claude_desktop_mcp_setup_step3.png" />
      </Step>

      <Step title="서버 세부 정보 입력">
        1. **Name** 필드(라벨 **5**)에 **Comfy Cloud MCP**와 같은 이름을 입력하세요.
        2. **Remote MCP server URL**을 `https://cloud.comfy.org/mcp`(라벨 **6**)로 설정하세요.
        3. **Add**(라벨 **7**)를 클릭하세요.

                   <img src="https://mintcdn.com/dripart-chore-sync-comfy-api-v2-spec-462120c/LqynrgyB_KXghPT7/images/agent_tools/claude_desktop_mcp_setup_step4.png?fit=max&auto=format&n=LqynrgyB_KXghPT7&q=85&s=c01613c2e0f1ec90a1bd2160d0631390" alt="Claude Desktop — connector details" width="1535" height="955" data-path="images/agent_tools/claude_desktop_mcp_setup_step4.png" />
      </Step>

      <Step title="로그인">
        1. 브라우저가 열리면 워크스페이스를 선택하세요(예: **Personal Workspace**).
        2. **Continue**를 클릭하여 커넥터를 승인하세요. 연결되었습니다.

                   <img src="https://mintcdn.com/dripart-chore-sync-comfy-api-v2-spec-462120c/LqynrgyB_KXghPT7/images/agent_tools/auth.png?fit=max&auto=format&n=LqynrgyB_KXghPT7&q=85&s=a42ed121afef86ffddbbd7056eaabb5d" alt="Comfy Cloud MCP authorization" width="2718" height="1480" data-path="images/agent_tools/auth.png" />
      </Step>
    </Steps>
  </Tab>

  <Tab title="Claude Code">
    **comfy-cloud** 플러그인을 설치하세요. MCP 연결과 슬래시 명령을 한 번에 추가합니다. 이 플러그인은 [Comfy Skills](https://github.com/Comfy-Org/comfy-skills/) 저장소를 통해 배포되며, Comfy용 Claude Code 플러그인과 커뮤니티 에이전트 스킬을 호스팅합니다.

    <Steps>
      <Step title="마켓플레이스 추가">
        Comfy Skills 마켓플레이스를 등록합니다(최초 1회):

        ```
        /plugin marketplace add Comfy-Org/comfy-skills
        ```
      </Step>

      <Step title="플러그인 설치">
        ```
        /plugin install comfy-cloud@comfy-skills
        ```
      </Step>

      <Step title="로그인">
        `/mcp`를 실행하고 **comfy-cloud** → **Authenticate**를 선택하세요. 브라우저가 열려 로그인되고 토큰이 자동으로 갱신됩니다.
      </Step>
    </Steps>

    플러그인은 다음 슬래시 명령을 추가합니다:

    | 명령                               | 설명                                                  |
    | -------------------------------- | --------------------------------------------------- |
    | `/comfy-cloud:generate-image`    | 이미지 생성, 편집 또는 수정                                    |
    | `/comfy-cloud:generate-video`    | 비디오 생성, 편집 또는 확장                                    |
    | `/comfy-cloud:generate-audio`    | 오디오, 음악 또는 사운드 효과 생성                                |
    | `/comfy-cloud:generate-3d`       | 텍스트나 이미지로 3D 모델 생성                                  |
    | `/comfy-cloud:remove-background` | 이미지에서 배경 제거                                         |
    | `/comfy-cloud:upscale-image`     | 이미지를 더 높은 해상도로 업스케일                                 |
    | `/comfy-cloud:search-templates`  | [comfy.org](https://comfy.org)에서 사전 제작된 워크플로 템플릿 찾기 |
    | `/comfy-cloud:search-models`     | 사용 가능한 모델 검색                                        |
    | `/comfy-cloud:search-nodes`      | 노드 검색 및 연결 제안 받기                                    |
    | `/comfy-cloud:help`              | ComfyUI Cloud로 할 수 있는 작업 확인                         |

    <Accordion title="플러그인 없이 연결만 원하시나요?">
      서버를 직접 추가하세요:

      ```bash theme={null}
      claude mcp add --transport http comfy-cloud https://cloud.comfy.org/mcp
      ```

      그런 다음 `/mcp`를 실행하고 **comfy-cloud** → **Authenticate**를 선택하세요. 모든 프로젝트에서 사용할 수 있도록 `-s user`를 추가하세요.

      이 경로는 여전히 MCP 프롬프트와 동일한 워크플로를 노출합니다: `/mcp__comfy-cloud__generate-image`, `/mcp__comfy-cloud__search-models` 등(`/mcp__<name>__` 접두사는 `claude mcp add`에 전달한 이름을 사용합니다). 위 플러그인이 권장되는 이유는 이러한 명령을 더 친근한 `/comfy-cloud:*` 명령으로 감싸기 때문입니다.
    </Accordion>
  </Tab>

  <Tab title="Cursor">
    Cursor는 HTTP를 통해 원격 MCP 서버에 연결합니다. Cursor는 현재 MCP OAuth를 지원하지 **않습니다**. MCP 구성에 Comfy Cloud API 키와 함께 Comfy Cloud를 추가하세요.

    <Steps>
      <Step title="Cursor Settings 열기">
        오른쪽 위 모서리의 **Settings** 톱니바퀴를 클릭하세요(라벨 **1**).

        <img src="https://mintcdn.com/dripart-chore-sync-comfy-api-v2-spec-462120c/LqynrgyB_KXghPT7/images/agent_tools/cursor_mcp_setup_step1.png?fit=max&auto=format&n=LqynrgyB_KXghPT7&q=85&s=e499adc78f743b60880278e73460f667" alt="Cursor — open Settings" width="2150" height="1516" data-path="images/agent_tools/cursor_mcp_setup_step1.png" />
      </Step>

      <Step title="Tools & MCP 열기">
        1. 사이드바에서 **Tools & MCPs**(라벨 **2**)를 클릭하세요.
        2. **+ New MCP Server**(라벨 **3**) → **Add a Custom MCP Server**를 클릭하세요.

                   <img src="https://mintcdn.com/dripart-chore-sync-comfy-api-v2-spec-462120c/LqynrgyB_KXghPT7/images/agent_tools/cursor_mcp_setup_step2.png?fit=max&auto=format&n=LqynrgyB_KXghPT7&q=85&s=8249ba5bae244cbe4bbaa1ac1073edc3" alt="Cursor — Tools & MCPs" width="2150" height="1516" data-path="images/agent_tools/cursor_mcp_setup_step2.png" />
      </Step>

      <Step title="API 키 추가">
        `~/.cursor/mcp.json`(글로벌) 또는 `.cursor/mcp.json`(프로젝트)을 편집하세요. 서버 URL을 설정하고 `X-API-Key` 헤더에 Comfy Cloud API 키를 전달하세요. [platform.comfy.org/profile/api-keys](https://platform.comfy.org/profile/api-keys)에서 키를 생성하세요(`comfyui-`로 시작):

        ```json theme={null}
        {
          "mcpServers": {
            "comfy-cloud": {
              "url": "https://cloud.comfy.org/mcp",
              "headers": {
                "X-API-Key": "${env:COMFY_API_KEY}"
              }
            }
          }
        }
        ```

        셸 또는 시스템 환경에 `COMFY_API_KEY`를 설정하세요. Git에 커밋할 수 있는 파일에 키를 하드코딩하는 대신 `${env:COMFY_API_KEY}`를 사용하는 것이 좋습니다.

        <img src="https://mintcdn.com/dripart-chore-sync-comfy-api-v2-spec-462120c/LqynrgyB_KXghPT7/images/agent_tools/cursor_mcp_setup_step3.png?fit=max&auto=format&n=LqynrgyB_KXghPT7&q=85&s=c68cf2b55121cf91a954a2e42e5c4b97" alt="Cursor — mcp.json with API key" width="2150" height="1516" data-path="images/agent_tools/cursor_mcp_setup_step3.png" />
      </Step>

      <Step title="생성 시작">
        평범한 언어로 요청하세요("고양이 우주 비행사 이미지 생성", "Wan 2.2 비디오 템플릿 찾기"). Cursor가 대신 MCP 도구를 호출합니다.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Codex">
    [Codex](https://developers.openai.com/codex/cli)는 Streamable HTTP를 통해 Comfy Cloud에 연결됩니다. Settings에서 서버를 추가한 후 OAuth로 로그인합니다.

    <video controls className="w-full aspect-video rounded-xl" src="https://mintcdn.com/dripart-chore-sync-comfy-api-v2-spec-462120c/LqynrgyB_KXghPT7/images/agent_tools/CodeX_Oauth_mcp.mp4?fit=max&auto=format&n=LqynrgyB_KXghPT7&q=85&s=e06ef3c8f576623db2a6419557fd2201" data-path="images/agent_tools/CodeX_Oauth_mcp.mp4" />

    <Steps>
      <Step title="설정 패널 열기">
        1. *Logged in with API key* 아래의 **Settings**(라벨 **1**)를 클릭하세요.
        2. **Settings**(라벨 **2**)를 클릭하여 전체 설정 패널을 엽니다.

                   <img src="https://mintcdn.com/dripart-chore-sync-comfy-api-v2-spec-462120c/LqynrgyB_KXghPT7/images/agent_tools/codex_mcp_setup_step1.png?fit=max&auto=format&n=LqynrgyB_KXghPT7&q=85&s=d90093051d316f100b2fc8c402bd2124" alt="Codex settings panel — step 1" width="1868" height="1278" data-path="images/agent_tools/codex_mcp_setup_step1.png" />
      </Step>

      <Step title="MCP 서버 설정 열기">
        1. 설정 목록에서 **MCP servers**(라벨 **3**)를 클릭하세요.
        2. **+ Add server**(라벨 **4**)를 클릭하여 새 MCP 서버를 추가합니다.

                   <img src="https://mintcdn.com/dripart-chore-sync-comfy-api-v2-spec-462120c/LqynrgyB_KXghPT7/images/agent_tools/codex_mcp_setup_step2.png?fit=max&auto=format&n=LqynrgyB_KXghPT7&q=85&s=e1f289136f21df4c0aa4709add777e59" alt="Codex MCP servers — step 2" width="1888" height="1364" data-path="images/agent_tools/codex_mcp_setup_step2.png" />
      </Step>

      <Step title="Comfy Cloud에 연결">
        1. 연결 유형으로 **Streamable HTTP**를 선택합니다.
        2. **Name** 필드(라벨 **5**)에 **Comfy Cloud MCP** 같은 이름을 입력합니다.
        3. **URL** 필드(라벨 **6**)에 `https://cloud.comfy.org/mcp` URL을 입력합니다.
        4. **Save**(라벨 **7**)를 클릭합니다.

                   <img src="https://mintcdn.com/dripart-chore-sync-comfy-api-v2-spec-462120c/LqynrgyB_KXghPT7/images/agent_tools/codex_mcp_setup_step3.png?fit=max&auto=format&n=LqynrgyB_KXghPT7&q=85&s=097ffc36b66843d1b32e5aeb9d175cc1" alt="Codex add MCP server — step 3" width="1888" height="1364" data-path="images/agent_tools/codex_mcp_setup_step3.png" />
      </Step>

      <Step title="Authenticate">
        1. 저장된 서버 항목에서 **Authenticate**(라벨 **8**)를 클릭합니다.

                   <img src="https://mintcdn.com/dripart-chore-sync-comfy-api-v2-spec-462120c/LqynrgyB_KXghPT7/images/agent_tools/codex_mcp_setup_step4.png?fit=max&auto=format&n=LqynrgyB_KXghPT7&q=85&s=db4e530570894809661ded8d974f46ca" alt="Codex authenticate MCP server — step 4" width="1888" height="1364" data-path="images/agent_tools/codex_mcp_setup_step4.png" />

        2. 브라우저 팝업에서 워크스페이스를 선택하고 **Continue**를 클릭하여 로그인을 완료합니다. 연결되었습니다.

                   <img src="https://mintcdn.com/dripart-chore-sync-comfy-api-v2-spec-462120c/LqynrgyB_KXghPT7/images/agent_tools/auth.png?fit=max&auto=format&n=LqynrgyB_KXghPT7&q=85&s=a42ed121afef86ffddbbd7056eaabb5d" alt="Comfy Cloud MCP authorization" width="2718" height="1480" data-path="images/agent_tools/auth.png" />
      </Step>
    </Steps>

    평범한 언어로 요청하세요("고양이 우주 비행사 이미지 생성", "Wan 2.2 비디오 템플릿 찾기"). Codex가 대신 MCP 도구를 호출합니다.

    <Accordion title="대신 CLI를 선호하시나요?">
      터미널에서 등록하고 로그인하세요:

      ```bash theme={null}
      codex mcp add comfy-cloud --url https://cloud.comfy.org/mcp
      codex mcp login comfy-cloud
      ```

      이 명령은 `~/.codex/config.toml`(신뢰할 수 있는 프로젝트에서는 `.codex/config.toml`)에 항목을 기록합니다.
    </Accordion>

    <Accordion title="OAuth 대신 API 키(헤드리스 또는 CI)">
      브라우저를 사용할 수 없는 경우, 환경 변수에서 가져온 헤더와 함께 서버를 추가하세요. [platform.comfy.org/profile/api-keys](https://platform.comfy.org/profile/api-keys)에서 키를 생성하세요(`comfyui-`로 시작). 그런 다음 `~/.codex/config.toml`에 추가하세요:

      ```toml theme={null}
      [mcp_servers.comfy-cloud]
      url = "https://cloud.comfy.org/mcp"
      env_http_headers = { "X-API-Key" = "COMFY_API_KEY" }
      ```

      셸 또는 시스템 환경에 `COMFY_API_KEY`를 설정하세요. 키를 버전 관리에 커밋하지 마세요.
    </Accordion>
  </Tab>

  <Tab title="OpenClaw">
    [ClawHub](https://clawhub.ai/comfy-org/skills/comfy)에서 **Comfy Cloud** 스킬을 설치하세요. OpenClaw를 호스팅된 MCP 서버(`cloud.comfy.org/mcp`)에 연결합니다. 클라우드 전용이며, 로컬 ComfyUI 설치를 구동하지 않습니다.

    <Steps>
      <Step title="스킬 설치">
        ```bash theme={null}
        openclaw skills install @comfy-org/comfy
        ```

        스킬 페이지: [clawhub.ai/comfy-org/skills/comfy](https://clawhub.ai/comfy-org/skills/comfy).
      </Step>

      <Step title="OAuth로 연결(권장)">
        MCP 서버를 등록하고 Comfy 계정으로 로그인하세요:

        ```bash theme={null}
        openclaw mcp set comfy '{"url":"https://cloud.comfy.org/mcp","transport":"streamable-http","auth":"oauth"}'
        openclaw mcp login comfy
        openclaw gateway restart
        ```

        `openclaw mcp login`은 인증 URL을 출력합니다. URL을 열어 로그인하고 CLI의 안내에 따라 흐름을 완료하세요(`--code` 값과 함께 다시 실행하라는 요청이 있을 수 있습니다). `openclaw mcp status --verbose`로 확인하세요.

        <Note>
          `auth: "oauth"`가 설정되면 OpenClaw는 해당 서버 항목의 정적 `headers`를 무시합니다. OAuth와 하드코딩된 API 키 헤더를 결합하지 마세요.
        </Note>
      </Step>

      <Step title="생성 시작">
        평범한 언어로 요청하세요("고양이 우주 비행사 이미지 생성", "Wan 2.2 비디오 템플릿 찾기"). OpenClaw가 대신 MCP 도구를 호출합니다.
      </Step>
    </Steps>

    <Accordion title="OAuth 대신 API 키(헤드리스 또는 CI)">
      [platform.comfy.org/profile/api-keys](https://platform.comfy.org/profile/api-keys)에서 키를 생성하세요(`comfyui-`로 시작), 내보낸 다음 서버를 등록하세요:

      ```bash theme={null}
      export COMFY_API_KEY="comfyui-..."
      openclaw mcp set comfy '{"url":"https://cloud.comfy.org/mcp","transport":"streamable-http","headers":{"Authorization":"Bearer ${COMFY_API_KEY}"}}'
      openclaw gateway restart
      ```

      OpenClaw에서는 사용자 정의 `X-API-Key` 헤더보다 `Authorization: Bearer`를 선호하세요. 일부 OpenClaw 빌드는 streamable-http 전송에서 사용자 정의 헤더를 삭제합니다. Bearer는 프록시를 더 안정적으로 통과합니다. `COMFY_API_KEY`를 셸 프로필이나 OpenClaw 환경에 넣으세요. 키를 커밋하지 마세요.
    </Accordion>
  </Tab>

  <Tab title="Other clients">
    **원격 HTTP** 전송을 지원하는 모든 MCP 클라이언트는 Comfy Cloud에 연결할 수 있습니다. 서버 URL은 항상 `https://cloud.comfy.org/mcp`입니다.

    <Steps>
      <Step title="서버 URL 추가">
        `https://cloud.comfy.org/mcp`를 가리키는 원격 MCP 항목을 추가하세요. 대부분의 클라이언트는 `url` 필드가 있는 JSON 설정을 사용합니다:

        ```json theme={null}
        {
          "mcpServers": {
            "comfy-cloud": {
              "url": "https://cloud.comfy.org/mcp"
            }
          }
        }
        ```

        **Windsurf**는 `url` 대신 `serverUrl`을 사용합니다. **Amp**는 **Settings → MCP Servers** 또는 `~/.config/amp/settings.json`에서 동일한 `mcpServers` 형태를 사용합니다.
      </Step>

      <Step title="Authenticate">
        클라이언트가 MCP OAuth를 지원하면 메시지가 표시될 때 브라우저를 통해 로그인하세요. 그렇지 않으면 API 키 헤더를 추가하세요(아래 참조).
      </Step>

      <Step title="재시작 및 확인">
        클라이언트를 재시작하세요. **comfy-cloud** 서버 아래에 Comfy Cloud 도구(`search_templates`, `submit_workflow`, `get_output` 등)가 등록되어 있어야 합니다.
      </Step>
    </Steps>

    **헤드리스 / CI(API 키):** OAuth를 사용할 수 없는 경우, [platform.comfy.org/profile/api-keys](https://platform.comfy.org/profile/api-keys)에서 키를 생성하고 `X-API-Key` 헤더로 전달하세요:

    ```json theme={null}
    {
      "mcpServers": {
        "comfy-cloud": {
          "url": "https://cloud.comfy.org/mcp",
          "headers": {
            "X-API-Key": "comfyui-…"
          }
        }
      }
    }
    ```

    터미널에서 Claude Code의 경우:

    ```bash theme={null}
    claude mcp add --transport http comfy-cloud https://cloud.comfy.org/mcp -H "X-API-Key: comfyui-…"
    ```

    Git에 커밋하는 설정 파일에 키를 하드코딩하는 대신 `${env:COMFY_API_KEY}` 또는 클라이언트의 비밀 보간(interpolation)을 사용하는 것이 좋습니다.
  </Tab>
</Tabs>

### 에이전트로 할 수 있는 일

MCP 도구를 직접 호출하지 않습니다. 에이전트가 사용자의 요청에 따라 적절한 도구를 선택합니다. 슬래시 명령과 프롬프트(아래 참조)는 에이전트를 일반적인 작업으로 유도하는 단축키이지만, 평범한 언어로도 사용할 수 있습니다("고양이 우주 비행사 이미지 생성", "이 사진을 업스케일해줘", "Wan 2.2 비디오 템플릿 찾아줘").

일반적인 흐름:

1. 사용 가능한 항목을 **탐색**합니다(`search_templates`, `search_models`, `search_nodes`, 그래프 스타일 문의에는 `cql` 사용).
2. 생성을 **실행**합니다: 일치하는 사전 제작 템플릿에는 `run_template`, 사용자 정의 워크플로에는 `submit_workflow`(입력 이미지가 필요할 때는 `upload_file` 사용), Flux, Grok, Gemini, OpenAI, Ideogram, Seedance와 같은 파트너 모델에는 `partner_generate`를 사용합니다.
3. 출력을 **대기하고 가져옵니다**(`wait_for_job` 후 `get_output`이 에이전트가 셸에서 실행하는 다운로드 명령을 반환합니다).

서버는 처음부터 워크플로를 구축하기보다 [사전 제작 템플릿](https://comfy.org/workflows)을 일치시키는 것을 선호하며, 이는 일반적으로 더 빠르고 더 나은 결과를 생성합니다.

### 클라우드 MCP 도구

연결되면 에이전트가 액세스할 수 있는 도구입니다. 이름은 MCP 클라이언트 로그 및 디버깅 출력에 표시되는 것과 일치합니다.

**탐색**

| 도구                    | 설명                                                                                                                                         |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `search_templates`    | [comfy.org](https://comfy.org/workflows)에서 텍스트, 태그, 미디어 유형 또는 모델별로 사전 제작된 워크플로 템플릿 검색                                                      |
| `get_template`        | 검사하거나 직접 편집할 수 있도록 템플릿의 전체 워크플로 JSON 가져오기                                                                                                  |
| `get_template_schema` | 런타임에 오버라이드할 수 있는 템플릿의 파라미터 확인                                                                                                              |
| `search_models`       | 텍스트, 유형, 베이스 모델 또는 소스별로 모델 카탈로그 검색                                                                                                         |
| `search_nodes`        | 텍스트, 카테고리 또는 입력/출력 유형별로 사용 가능한 노드 검색. **서브그래프 블루프린트**(Text to Image 또는 Remove Background와 같은 사전 배선된 노드 그룹)도 표시                             |
| `get_node`            | 특정 노드의 전체 입력 사양 가져오기(전체 옵션 목록 포함)                                                                                                          |
| `cql`                 | 구조적 질문(예: 어떤 노드가 이미지를 생성하는지, 또는 노드 유형 간 경로)을 위해 [CQL](https://github.com/Comfy-Org/cql) 그래프 쿼리 실행. 특정 노드의 전체 입력 사양이 필요하면 `search_nodes` 사용 |
| `get_prompting_guide` | 모델 제품군별 프롬프트 스타일과 권장 설정(스텝, cfg, sampler, 해상도)                                                                                             |

**생성**

| 도구                 | 설명                                                                            |
| ------------------ | ----------------------------------------------------------------------------- |
| `run_template`     | 이름으로 사전 제작된 템플릿 실행(선택적으로 파라미터 오버라이드). 템플릿이 적합한 경우 선호되는 경로                     |
| `submit_workflow`  | ComfyUI API 형식의 워크플로를 Comfy Cloud에서 실행하도록 제출                                  |
| `partner_generate` | 파트너 API 모델(Flux/BFL, Grok, Gemini, OpenAI, Ideogram, Seedream/Seedance 등)로 생성 |
| `upload_file`      | 워크플로에서 사용할 입력 이미지 또는 파일 업로드(예: LoadImage 사용)                                  |
| `apply_slots`      | 워크플로의 내부 값에 파라미터 오버라이드 적용 후 수정된 워크플로 반환                                       |

**작업 및 배치**

| 도구                                                                       | 설명                                              |
| ------------------------------------------------------------------------ | ----------------------------------------------- |
| `get_job_status`                                                         | 제출된 워크플로의 실행 상태 폴링                              |
| `wait_for_job`                                                           | 반복적으로 폴링하지 않고 작업이 완료될 때까지 대기                    |
| `get_output`                                                             | 완료된 워크플로에서 출력 이미지, 비디오 또는 오디오 가져오기              |
| `use_previous_output`                                                    | 한 실행의 출력을 다른 실행의 입력으로 재사용하여 워크플로 연결             |
| `cancel_job`                                                             | 대기 중이거나 실행 중인 작업 취소                             |
| `get_queue`                                                              | 실행 중이거나 대기 중인 작업 수 확인                           |
| `submit_batch`, `get_batch_status`, `get_batch_output`, `wait_for_batch` | 한 번의 호출로 여러 생성을 제출하고 나중에 함께 수집. 배치 ID는 세션 간에 유효 |

**저장된 워크플로**

| 도구                     | 설명                                                 |
| ---------------------- | -------------------------------------------------- |
| `list_saved_workflows` | Comfy Cloud에서 저장된 워크플로 찾아보기                        |
| `get_saved_workflow`   | 저장된 워크플로의 노드, 입력 및 사용자 정의 가능한 설정 검사                |
| `save_workflow`        | Comfy Cloud 계정에 워크플로 저장                            |
| `update_workflow`      | 기존 워크플로를 새 버전으로 바로 업데이트(이전 버전은 복구 가능하게 유지)         |
| `run_saved_workflow`   | 파일 이름으로 저장된 워크플로 실행. 서버가 편집기 형식에서 실행 가능 형식으로 자동 변환 |

**워크플로 공유**

| 도구                       | 설명                                               |
| ------------------------ | ------------------------------------------------ |
| `share_workflow`         | 저장된 워크플로를 게시하고 누구나 열 수 있는 `?share=<id>` URL 반환   |
| `import_shared_workflow` | 공유 URL 또는 단순 공유 ID를 워크플로 JSON으로 변환(선택적으로 계정에 저장) |

**Hub URL 공유 ID:** `comfy.org/workflows/<slug>-<hex>` hub URL에서 뒤에 붙은 하이픈으로 구분된 16진수 토큰이 공유 ID입니다. 예를 들어, `comfy.org/workflows/topaz-starlight-upscale-1c77e82713b7`의 공유 ID는 `1c77e82713b7`입니다. 이 토큰을 `import_shared_workflow`에 `share_id`로 전달하세요. `share_url` 매개변수는 `https://cloud.comfy.org/?share=...`와 같은 `?share=<id>` 쿼리 URL만 허용하며, hub 페이지 URL은 허용하지 않습니다.

**앱 및 링크**

| 도구                        | 설명                                                            |
| ------------------------- | ------------------------------------------------------------- |
| `create_app`              | 저장된 워크플로를 App Mode 앱으로 변환. 선택한 입력과 출력을 가진 간소화된 "이 워크플로 실행" 보기 |
| `get_app_mode_url`        | 워크플로를 실행 가능한 앱으로 열 수 있는 안정적인 링크 가져오기                          |
| `get_workflow_canvas_url` | 워크플로를 Comfy Cloud 캔버스에서 직접 열 수 있는 링크 가져오기(보기, 편집 또는 실행 준비 완료) |

**계정 및 세션**

| 도구                       | 설명                                                                                              |
| ------------------------ | ----------------------------------------------------------------------------------------------- |
| `get_billing_status`     | 크레딧 잔액, 구독 등급, 결제 링크 확인                                                                         |
| `get_server_info`        | 에이전트가 연결한 서버 확인: 환경, 호스트, 버전, 인증 상태                                                             |
| `submit_feedback`        | 베타 피드백 설문조사 링크 가져오기                                                                             |
| `report_session_summary` | 익명화된 세션 요약을 Comfy 팀과 공유. **명시적 동의가 있는 경우에만** 진행하며, 에이전트가 먼저 요청해야 함. 프롬프트, 파일 경로, 개인 정보는 포함되지 않음 |

**프롬프트(Claude Desktop)**

Claude Desktop은 Claude Code 슬래시 명령을 지원하지 않습니다. 대신 **prompt picker**를 열어 동일한 워크플로를 사용하세요:

| 프롬프트                | 설명                           |
| ------------------- | ---------------------------- |
| `generate-image`    | 텍스트 설명에서 이미지 생성              |
| `generate-video`    | 텍스트 또는 이미지에서 비디오 생성          |
| `generate-audio`    | 오디오, 음악, 사운드 효과 생성           |
| `generate-3d`       | 텍스트 또는 이미지에서 3D 모델 생성        |
| `upscale-image`     | 이미지를 더 높은 해상도로 업스케일          |
| `remove-background` | 이미지에서 배경 제거                  |
| `search-templates`  | 사전 제작된 워크플로 템플릿 찾기           |
| `search-models`     | 모델 검색(checkpoint, LoRA, VAE) |
| `search-nodes`      | 노드 검색 및 연결 제안 받기             |
| `help`              | ComfyUI Cloud로 할 수 있는 작업 확인  |

프롬프트를 건너뛰고 평범한 언어로 요청할 수도 있습니다. MCP 도구는 동일한 방식으로 작동합니다.

### 크레딧과 비용

탐색은 무료입니다: `search_templates`, `search_models`, `search_nodes`는 [Comfy 계정](https://cloud.comfy.org)만 있으면 작동합니다. 생성을 실행하려면 활성 Comfy Cloud 구독이 필요합니다. 크레딧이나 충전 잔액만으로는 접근 권한이 주어지지 않습니다. 사용하지 않은 크레딧이 있어도 생성을 실행하려면 활성 구독이 필요합니다.

### 업로드 및 다운로드

MCP 서버는 클라우드에서 실행되며 MCP 자체는 사용자 머신에 파일을 쓰지 않습니다. 생성이 완료되면 에이전트가 `get_output`을 호출하고, 다음을 반환합니다:

1. **임시 서명된 다운로드 URL**(짧은 시간 동안 유효).
2. 바로 실행 가능한 **셸 명령**(macOS와 Linux에서는 `curl`, Windows에서는 `curl.exe`).

에이전트는 이 명령을 셸에서 실행해야 합니다. 명령에는 대상 경로와 파일 이름이 포함되어 있습니다.

<Warning>
  반환된 명령을 **그대로** 실행하세요. 서명된 URL을 다시 인코딩하거나 편집하지 마세요. 서명은 쿼리 문자열에 있으며 URL을 수정하면 깨집니다.
</Warning>

MCP 클라이언트가 셸 명령을 실행할 수 없는 경우(일부 GUI 전용 설정), 명령을 복사하여 터미널에서 직접 실행하세요.

에셋 업로드와 다운로드는 클라이언트의 파일 접근에 의존합니다. Claude Desktop이나 다른 에이전트 클라이언트가 에셋 업로드 또는 다운로드를 처리하는 데 문제가 있다면, 에이전트의 로컬 파일 디렉터리 접근과 관련이 있을 수 있습니다. Claude 사용자에게는 더 많은 기능을 갖춘 **Claude Code**(데스크톱 앱 또는 터미널)를 권장합니다. 마찬가지로, 다른 에이전트 계열에서는 일반적으로 코딩 에이전트가 웹 채팅 버전보다 낫습니다.

### 알려진 제한 사항

Comfy Cloud MCP는 초기 릴리스입니다. 다음과 같은 알려진 제한 사항이 있으며, 해결을 위해 작업 중입니다:

**워크플로**

* **`submit_workflow`를 통해 생성된 에셋에는 워크플로 메타데이터가 포함되지 않을 수 있습니다.** ComfyUI에서 열 때 원래 워크플로가 다시 열리지 않을 수 있습니다.
* **워크플로 빌드는 에이전트의 정확도에 따라 달라집니다.** 복잡한 다중 노드 워크플로는 재시도나 수정이 필요할 수 있습니다.

**파일 처리**

* **출력물은 셸 다운로드 단계가 필요합니다.** [업로드 및 다운로드](#업로드-및-다운로드)를 참조하세요.
* **업로드 크기 제한**은 MCP 클라이언트에 따라 적용될 수 있습니다. 일부 클라이언트는 자체적으로 파일 업로드 크기 제한을 부과합니다.

**인증**

* **OAuth 또는 API 키.** Claude Code와 Claude Desktop은 일회성 브라우저 OAuth 흐름을 사용합니다. **Cursor**는 MCP 구성에 Comfy Cloud API 키가 필요합니다(OAuth 없음). 다른 헤드리스 클라이언트는 대신 `X-API-Key` 헤더를 통해 Comfy Cloud API 키를 전달할 수 있습니다. 브라우저를 열 수 없는 클라이언트를 위한 디바이스 코드 OAuth 흐름이 계획되어 있습니다.

## 로컬 Comfy MCP 연결

오픈소스 연결: 클라이언트가 머신에서 서버를 시작하고, 그 서버가 해당 머신에 설치된 ComfyUI를 구동합니다.

[**comfy-mcp**](https://github.com/Comfy-Org/comfy-mcp)는 Comfy의 **퍼스트파티 로컬 MCP 서버**입니다. AI 에이전트(Claude Code, Claude Desktop, Cursor 및 기타 MCP 클라이언트)에서 **로컬** ComfyUI 설치를 구동하는 공식 방법입니다.

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

<Tip>
  **가장 빠른 설정 방법: 에이전트에게 맡기세요.** AI 클라이언트에 `https://docs.comfy.org/agent-tools/mcp#installation`을 붙여넣고 로컬 연결 설정을 요청하세요.
</Tip>

### 요구 사항

* **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`로 시작하거나 `launch_comfyui`를 호출하세요. 서버는 ComfyUI를 암시적으로 시작하지 않습니다.

***

### 설치

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

```bash theme={null}
pip install comfy-mcp
```

이렇게 하면 `comfy-mcp` 콘솔 스크립트가 `PATH`에 추가됩니다. 이 명령이 MCP 서버이며(stdio를 통해 MCP 통신), AI 클라이언트가 아래에서 이 서버를 가리키도록 설정하세요.

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

***

### 수동 구성

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

<Tabs>
  <Tab title="Claude Desktop">
    `claude_desktop_config.json`을 편집하고(Settings → Developer → Edit Config. macOS의 경우 `~/Library/Application Support/Claude/claude_desktop_config.json`에 위치), 서버를 추가한 다음 Claude Desktop을 재시작합니다:

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

  <Tab title="Claude Code">
    한 줄의 명령으로 서버를 등록합니다:

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

    또는 저장소 루트에 `.mcp.json` 파일을 만들어 프로젝트에 등록할 수도 있습니다:

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

  <Tab title="Cursor">
    서버를 `~/.cursor/mcp.json`(전역) 또는 `.cursor/mcp.json`(프로젝트별)에 추가합니다:

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

***

### 빠른 시작

처음부터 생성 이미지까지:

<Steps>
  <Step title="필수 구성 요소 설치">
    ```bash theme={null}
    git clone https://github.com/Comfy-Org/comfy-mcp
    cd comfy-mcp
    pip install "comfy-cli>=1.14.0"  # the engine
    comfy install             # create a ComfyUI workspace (skip if you have one)
    pip install comfy-mcp            # this MCP server → the `comfy-mcp` command
    ```
  </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`를 통해 워크플로 사전 검증        |

노드 인트로스펙션과 모델 검색은 **실행 중인 설치**를 읽습니다. 커스텀 노드가 포함되며, 이것이 클라우드 연결과 구별되는 로컬의 특징입니다. 전체 도구 목록과 참조는 [저장소](https://github.com/Comfy-Org/comfy-mcp)를 확인하세요.

***

## 관련 리소스

| 리소스                                                               | 설명                                                                                                                           |
| ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| [Comfy Skills](https://github.com/Comfy-Org/comfy-skills/)        | Claude Code 플러그인 마켓플레이스이자 커뮤니티 스킬 라이브러리. 위에서 사용된 **comfy-cloud** 플러그인이 여기에 배포되어 있으며, Comfy 워크플로를 위한 추가 스킬을 찾아보거나 기여할 수 있습니다. |
| [ClawHub의 Comfy Cloud](https://clawhub.ai/comfy-org/skills/comfy) | 호스팅된 Comfy Cloud MCP 서버용 OpenClaw 스킬(`openclaw skills install @comfy-org/comfy`).                                            |
| [Comfy CLI](/ko/agent-tools/cli)                                  | 로컬 ComfyUI 설치/실행 및 스크립트나 CI에서 호스팅된 파트너 노드를 호출하기 위한 명령줄 도구(`comfy generate`, 베타). 터미널이나 자동화 워크플로가 필요할 때 MCP를 보완합니다.           |
| [Comfy Cloud에서 워크플로 공유하기](/ko/cloud/share-workflow)               | Comfy Cloud UI에서 워크플로를 공유합니다(MCP `share_workflow` 도구가 에이전트 세션에서 이 작업을 수행합니다).                                                |

## 관련 항목: Comfy 인앱 에이전트

외부 MCP 클라이언트가 아닌, **Comfy Cloud 내부**에서 에이전트 경험(그래프를 빌드하고 편집하는 채팅)을 원하시나요?

<Card title="Comfy 인앱 에이전트" icon="comments" href="/ko/agent-tools/in-app-agent">
  Comfy Cloud의 비공개 알파입니다. 액세스를 요청하려면 웨이팅 리스트에 참여하세요.
</Card>

## 피드백

Comfy MCP는 공개 베타 단계입니다. 사용해 보시고 작동하는 점과 그렇지 않은 점을 알려주세요:

* **[피드백 설문조사](https://links.comfy.org/cloudmcpbeta)**: 버그 신고, 기능 요청 또는 일반적인 소감을 공유하세요.
* **Discord**: Comfy Discord의 [#comfy-mcp-and-cli](https://discord.gg/xWJn6nhE3R)에서 문의 및 토론하세요.

## FAQ

### 시작하기

<AccordionGroup>
  <Accordion title="어떤 클라이언트가 지원되나요?">
    MCP와 호환되는 모든 클라이언트가 지원됩니다.

    **클라우드 연결**은 원격 HTTP 지원이 필요합니다. **Claude Code**, **Claude Desktop**, **Cursor**, **Codex**, **OpenClaw**는 위에서 가장 간편하게 설정할 수 있습니다. **Windsurf**, **Amp** 등도 OAuth나 API 키와 함께 같은 URL을 사용합니다.

    **로컬 연결**은 로컬 stdio 서버를 하위 프로세스로 실행할 수 있는 클라이언트가 필요합니다. 따라서 브라우저 기반 클라이언트는 사용할 수 없습니다. [claude.ai](https://claude.ai)와 ChatGPT는 원격 커넥터만 허용합니다.
  </Accordion>

  <Accordion title="서버 URL은 무엇인가요?">
    클라우드 연결은 `https://cloud.comfy.org/mcp`에서 실행됩니다.

    로컬 연결에는 URL이 없습니다. 클라이언트가 `comfy-mcp` 명령을 직접 실행하고 stdio를 통해 통신합니다.
  </Accordion>

  <Accordion title="내 로컬 ComfyUI와 함께 사용할 수 있나요?">
    사용할 수 있습니다. 바로 [로컬 Comfy MCP 연결](#로컬-comfy-mcp-연결)입니다. 직접 설치한 ComfyUI를 구동하므로, 에이전트가 실제로 보유한 모델, LoRA, 커스텀 노드를 인식하고 여러분의 GPU에서 실행됩니다.
  </Accordion>

  <Accordion title="클라우드 연결과 로컬 연결을 동시에 사용할 수 있나요?">
    네, 로컬에서 ComfyUI를 실행한다면 이 방법을 권장합니다. 대부분의 클라이언트는 두 개의 MCP 서버를 문제없이 호스팅하며, 에이전트는 각 연결을 분리하여 처리합니다. 각 연결은 자체 워크플로를 실행하고 자체 결과를 반환합니다.

    단, 두 연결의 로그인은 **별도**로 진행해야 합니다. 동일한 Comfy 계정이라도 한쪽에서 로그인했다고 다른 쪽이 자동으로 로그인되지는 않습니다.
  </Accordion>

  <Accordion title="내 컴퓨터가 로컬 연결을 실행할 수 있는지 어떻게 알 수 있나요?">
    에이전트에게 물어보세요. 무거운 작업을 시작하기 전에 에이전트가 하드웨어를 확인합니다.

    **Mac**에서는 생성 작업에 클라우드 연결을 사용하세요. 현재의 오픈웨이트 모델은 Apple GPU에서 실용적인 속도로 실행하기에는 너무 큽니다. **전용 그래픽 카드가 있는 PC**의 경우, VRAM이 24GB 이상이면 비디오를 포함한 대부분의 작업을 처리할 수 있습니다. 8\~24GB는 이미지에 적합하지만 비디오는 느리거나 맞지 않을 수 있습니다. 8GB 미만이라면 클라우드를 사용하세요.
  </Accordion>

  <Accordion title="일반 공개되었나요?">
    클라우드 연결은 **공개 베타** 상태입니다. API, 도구, 동작은 개발 과정에서 변경될 수 있습니다. 문제를 신고하려면 [피드백](#피드백)을 참고하세요.
  </Accordion>
</AccordionGroup>

### 비용과 접근

<AccordionGroup>
  <Accordion title="비용이 발생하나요?">
    탐색은 두 연결 모두에서 무료입니다. 템플릿, 모델, 노드를 검색하는 데는 Comfy 계정만 있으면 됩니다.

    **클라우드 연결**에서는 생성을 실행하려면 활성 Comfy Cloud 구독이 필요합니다. 신규 사용자에게는 5회의 무료 실행이 제공됩니다. **로컬 연결**에서는 사용자 하드웨어에서 실행되므로 무료입니다. 단, 한 가지 예외가 있습니다: 파트너 모델은 파트너 인프라에서 실행되며 크레딧이 소모됩니다.
  </Accordion>

  <Accordion title="API 키가 필요한가요?">
    OAuth를 지원하는 인터랙티브 클라이언트에서는 필요하지 않습니다. Claude Code, Claude Desktop, Codex, OpenClaw 등이 여기에 해당합니다.

    **Cursor**는 MCP 구성에 Comfy Cloud API 키가 필요합니다. 아직 MCP OAuth를 지원하지 않기 때문입니다. 브라우저가 없는 헤드리스 및 CI 환경에서도 API 키가 필요합니다. [클라우드 연결 설정](#클라우드-연결-설정)의 **Cursor** 및 **Other clients** 탭을 참조하세요.
  </Accordion>
</AccordionGroup>

### 사용하기

<AccordionGroup>
  <Accordion title="에이전트가 연결되면 어떤 작업을 할 수 있나요?">
    MCP 도구를 직접 호출하지 않습니다. 사용자의 요청에 따라 에이전트가 선택합니다. 일반적으로 사용 가능한 항목을 **탐색**하고(`search_templates`, `search_models`, `search_nodes`), 생성을 **실행**한 후 출력을 **기다렸다가 가져옵니다**. 자세한 내용은 [에이전트로 할 수 있는 일](#에이전트로-할-수-있는-일)을 참고하세요.
  </Accordion>

  <Accordion title="출력 결과는 어디에 저장되나요?">
    **클라우드 연결**에서는 서버가 사용자의 머신에 기록하지 않습니다. `get_output`은 임시 서명된 URL과 셸에서 실행할 수 있는 다운로드 명령을 반환합니다. 자세한 내용은 [업로드 및 다운로드](#업로드-및-다운로드)를 참고하세요.

    **로컬 연결**에서는 ComfyUI가 워크스페이스의 `output/` 디렉터리에 파일을 기록하며, `fetch_outputs(prompt_id, out_dir)`는 완료된 작업의 파일을 지정한 경로로 복사합니다.
  </Accordion>

  <Accordion title="한 연결로 시작했는데 다른 연결도 필요할 때는 어떻게 하나요?">
    실행 취소할 것은 없습니다. 기존 연결에 두 번째 연결을 추가하기만 하면 됩니다.

    **로컬 → 클라우드**로 전환할 때(클라우드 GPU 또는 파트너 모델이 필요할 때): 에이전트에게 로그인하라고 요청한 다음 클라이언트에 `https://cloud.comfy.org/mcp`를 추가하세요.

    **클라우드 → 로컬**로 전환할 때(자신의 모델과 커스텀 노드를 사용하고 싶을 때): ComfyUI와 로컬 서버를 설치한 다음 클라이언트가 이를 가리키도록 설정하세요. 에이전트가 대부분의 작업을 대신해 줍니다.
  </Accordion>

  <Accordion title="로컬 연결과 클라우드 연결을 어떻게 전환하나요?">
    에이전트에게 요청하기만 하면 됩니다. 두 연결이 모두 추가된 상태에서 작업을 실행할 위치를 말하세요: "이 작업을 Comfy Cloud에서 실행해 줘", "로컬에서 이 작업을 해 줘"라고 하면 에이전트가 적절한 연결을 사용합니다. 실행 간에 전환할 모드도 없고 재설정할 것도 없습니다.

    워크플로가 기기에 너무 무겁다고 판단되면, 에이전트가 알려주며 Comfy Cloud에서 대신 실행하도록 제안할 수 있습니다. 하나의 연결만 설정되어 있다면, 다른 연결을 추가하도록 요청하세요. 자세한 내용은 [클라우드 연결 설정](#클라우드-연결-설정) 또는 [로컬 Comfy MCP 연결](#로컬-comfy-mcp-연결)을 참고하세요.
  </Accordion>

  <Accordion title="Comfy MCP를 업데이트하는 방법은?">
    **클라우드 연결**에서는 할 일이 없습니다. 호스팅되기 때문에 항상 최신 버전을 사용 중입니다.

    **로컬 연결**에서는 에이전트에게 처리하도록 요청하세요. 그 후, **클라이언트를 재시작**하거나 새 세션을 시작하세요. MCP 서버는 세션이 시작될 때 로드되므로, 실행 중인 서버는 재시작하거나 새 세션을 시작하기 전까지 이전 버전을 계속 제공합니다.
  </Accordion>
</AccordionGroup>

### 트러블슈팅

<AccordionGroup>
  <Accordion title="Claude Desktop에서 슬래시 명령이 작동하나요?">
    아니요. 슬래시 명령은 Claude Code 플러그인에서 제공됩니다. Claude Desktop은 동일한 MCP 서버에 연결되며, 평범한 언어로 요청하거나 prompt picker를 사용하면 도구가 작동합니다. 하지만 Claude Code 플러그인이나 슬래시 명령은 지원되지 않습니다.
  </Accordion>

  <Accordion title="/comfy 또는 /cloud를 입력했는데 아무 것도 나타나지 않았습니다.">
    `/comfy` 또는 `/cloud` 명령은 없습니다. 연결 방법에 따라 명령이 다음 두 접두사 중 하나로 나타납니다:

    * **플러그인(권장):** `/comfy-cloud:generate-image`, `/comfy-cloud:generate-video`, … — 모두 보려면 `/comfy-cloud:`를 입력하세요.
    * **직접 연결(플러그인 없음):** `/mcp__comfy-cloud__generate-image`, … — 보려면 `/mcp__`를 입력하세요.

    어느 쪽이든 평범한 언어로 요청할 수 있습니다("...의 이미지를 생성해 줘"). MCP 도구는 모델이 호출하므로 슬래시 명령이 필요하지 않습니다.
  </Accordion>

  <Accordion title="로그인할 때 브라우저가 열리지 않았습니다.">
    Claude Code에서는 `/mcp`를 실행하고 **comfy-cloud**를 선택한 다음 **Authenticate**를 선택합니다. Claude Desktop에서는 **Customize → Connectors**에서 커넥터를 다시 열고 로그인을 트리거합니다.
  </Accordion>
</AccordionGroup>