diff --git a/agent-tools/cloud.mdx b/agent-tools/cloud.mdx index 0f7059c95..997c51598 100644 --- a/agent-tools/cloud.mdx +++ b/agent-tools/cloud.mdx @@ -1,7 +1,7 @@ --- title: "Comfy Cloud MCP" sidebarTitle: "Cloud MCP" -description: "Use Comfy Cloud from Claude Code and Claude Desktop through the Comfy Cloud MCP server — generate images, video, audio, and 3D, search models and nodes, and run workflows." +description: "Connect Comfy Cloud MCP from Claude Code, Claude Desktop, Cursor, Codex, or any MCP-compatible agent — generate images, video, audio, and 3D, search models and nodes, and run workflows." icon: "cloud" --- @@ -19,7 +19,294 @@ The **Comfy Cloud MCP server** connects AI agents to [Comfy Cloud](https://cloud The server runs remotely at `cloud.comfy.org/mcp`. Workflows execute on Comfy Cloud GPUs, so you do not need a local GPU. Your agent talks to the server over HTTPS; the server translates tool calls into authenticated requests to Comfy Cloud on your behalf. -Support is currently scoped to **Claude Code** and **Claude Desktop**, which sign in with **OAuth** (a one-time browser sign-in). Support for more clients is coming. +Any **MCP-compatible client** can connect to the same server URL. **Claude Code**, **Claude Desktop**, **Cursor**, and **Codex** have first-class setup below. **Windsurf**, **Amp**, and other agents use the same URL with OAuth or an API key. + +## Install Comfy Cloud MCP + + + You need a [Comfy Cloud](https://cloud.comfy.org) account before connecting. [Sign up](https://cloud.comfy.org) if you do not have one yet. OAuth sign-in during setup uses your Comfy account. + + +Comfy Cloud MCP runs at: + +``` +https://cloud.comfy.org/mcp +``` + +Pick your client: + + + + Install the **comfy-cloud** plugin. It adds the MCP connection and slash commands in one step. The plugin is published through the [Comfy Skills](https://github.com/Comfy-Org/comfy-skills/) repository, which hosts Claude Code plugins and community agent skills for Comfy. + + + + Register the Comfy Skills marketplace (one-time): + + ``` + /plugin marketplace add Comfy-Org/comfy-skills + ``` + + + ``` + /plugin install comfy-cloud@comfy-skills + ``` + + + Run `/mcp`, select **comfy-cloud** → **Authenticate**. Your browser opens to sign in, and tokens refresh automatically. + + + + The plugin adds these slash commands: + + | Command | What it does | + | --- | --- | + | `/comfy-cloud:generate-image` | Generate, edit, or modify an image | + | `/comfy-cloud:generate-video` | Generate, edit, or extend a video | + | `/comfy-cloud:generate-audio` | Generate audio, music, or sound effects | + | `/comfy-cloud:generate-3d` | Generate a 3D model from text or an image | + | `/comfy-cloud:remove-background` | Remove the background from an image | + | `/comfy-cloud:upscale-image` | Upscale an image to higher resolution | + | `/comfy-cloud:search-templates` | Find pre-built workflow templates on [comfy.org](https://comfy.org) | + | `/comfy-cloud:search-models` | Search for available models | + | `/comfy-cloud:search-nodes` | Search for nodes and get wiring suggestions | + | `/comfy-cloud:help` | See what you can do with ComfyUI Cloud | + + + Add the server directly: + + ```bash + claude mcp add --transport http comfy-cloud https://cloud.comfy.org/mcp + ``` + + Then run `/mcp`, select **comfy-cloud** → **Authenticate**. Add `-s user` to make it available in all your projects. + + This path still exposes the same workflows as MCP prompts: `/mcp__comfy-cloud__generate-image`, `/mcp__comfy-cloud__search-models`, and so on (the `/mcp____` prefix uses the name you passed to `claude mcp add`). The plugin above is recommended because it wraps these as the friendlier `/comfy-cloud:*` commands. + + + + + Claude Desktop adds Comfy Cloud as a **custom connector** through its UI, then runs the OAuth sign-in. + + + + + + In the sidebar, click **Customize** (labeled **1**). + + ![Claude Desktop — open Customize](/images/agent_tools/claude_desktop_mcp_setup_step1.png) + + + Click **Connectors** (labeled **2**). + + ![Claude Desktop — open Connectors](/images/agent_tools/claude_desktop_mcp_setup_step2.png) + + + 1. Click the **+** button (labeled **3**) in the Connectors header. + 2. Choose **Add custom connector** (labeled **4**). + + ![Claude Desktop — add custom connector](/images/agent_tools/claude_desktop_mcp_setup_step3.png) + + + 1. Enter a name such as **Comfy Cloud MCP** in the **Name** field (labeled **5**). + 2. Set the **Remote MCP server URL** to `https://cloud.comfy.org/mcp` (labeled **6**). + 3. Click **Add** (labeled **7**). + + ![Claude Desktop — connector details](/images/agent_tools/claude_desktop_mcp_setup_step4.png) + + + 1. When the browser opens, choose your workspace (for example **Personal Workspace**). + 2. Click **Continue** to authorize the connector. You are connected. + + ![Comfy Cloud MCP authorization](/images/agent_tools/auth.png) + + + + Claude Desktop does not support Claude Code slash commands. Instead, open the **prompt picker** for the same workflows: + + | Prompt | Description | + | --- | --- | + | `generate-image` | Generate an image from a text description | + | `generate-video` | Generate a video from text or an image | + | `generate-audio` | Generate audio, music, or sound effects | + | `generate-3d` | Generate a 3D model from text or an image | + | `upscale-image` | Upscale an image to higher resolution | + | `remove-background` | Remove the background from an image | + | `search-templates` | Find pre-built workflow templates | + | `search-models` | Search for models (checkpoints, LoRAs, VAEs) | + | `search-nodes` | Search nodes and get wiring suggestions | + | `help` | See what you can do with ComfyUI Cloud | + + You can also skip prompts and ask in plain language. The MCP tools work the same way. + + + + Cursor connects to remote MCP servers over HTTP. Add Comfy Cloud in **Cursor Settings → Tools & MCP**, or edit your MCP config file directly. + + + + Create or edit `.cursor/mcp.json` in your project, or `~/.cursor/mcp.json` for a global setup: + + ```json + { + "mcpServers": { + "comfy-cloud": { + "url": "https://cloud.comfy.org/mcp" + } + } + } + ``` + + + Open **Cursor Settings → Tools & MCP**. Select **comfy-cloud** and click **Connect** to sign in through your browser (OAuth). Tokens refresh automatically. + + + Ask in plain language ("generate an image of a cat astronaut", "find a Wan 2.2 video template"). Cursor invokes the MCP tools on your behalf. + + + + + When no browser is available, pass a Comfy Cloud API key in the `X-API-Key` header. Create one at [platform.comfy.org/profile/api-keys](https://platform.comfy.org/profile/api-keys) (starts with `comfyui-`): + + ```json + { + "mcpServers": { + "comfy-cloud": { + "url": "https://cloud.comfy.org/mcp", + "headers": { + "X-API-Key": "${env:COMFY_API_KEY}" + } + } + } + } + ``` + + Set `COMFY_API_KEY` in your shell or system environment. Do not commit the key to version control. + + + + + [Codex](https://developers.openai.com/codex/cli) connects to Comfy Cloud over Streamable HTTP. Add the server in Settings, then sign in with OAuth. + + + + + + 1. Click **Settings** (labeled **1**) under *Logged in with API key*. + 2. Click **Settings** (labeled **2**) to open the full settings panel. + + ![Codex settings panel — step 1](/images/agent_tools/codex_mcp_setup_step1.png) + + + 1. Click **MCP servers** (labeled **3**) in the settings list. + 2. Click **+ Add server** (labeled **4**) to add a new MCP server. + + ![Codex MCP servers — step 2](/images/agent_tools/codex_mcp_setup_step2.png) + + + 1. Choose **Streamable HTTP** as the connection type. + 2. Enter a name such as **Comfy Cloud MCP** in the **Name** field (labeled **5**). + 3. Enter the URL `https://cloud.comfy.org/mcp` in the **URL** field (labeled **6**). + 4. Click **Save** (labeled **7**). + + ![Codex add MCP server — step 3](/images/agent_tools/codex_mcp_setup_step3.png) + + + 1. Click **Authenticate** (labeled **8**) on the saved server entry. + + ![Codex authenticate MCP server — step 4](/images/agent_tools/codex_mcp_setup_step4.png) + + 2. In the browser popup, choose your workspace and click **Continue** to finish signing in. You are connected. + + ![Comfy Cloud MCP authorization](/images/agent_tools/auth.png) + + + + Ask in plain language ("generate an image of a cat astronaut", "find a Wan 2.2 video template"). Codex invokes the MCP tools on your behalf. + + + Register and sign in from the terminal: + + ```bash + codex mcp add comfy-cloud --url https://cloud.comfy.org/mcp + codex mcp login comfy-cloud + ``` + + This writes an entry to `~/.codex/config.toml` (or `.codex/config.toml` in a trusted project). + + + + When no browser is available, add the server with a header pulled from an environment variable. Create a key at [platform.comfy.org/profile/api-keys](https://platform.comfy.org/profile/api-keys) (starts with `comfyui-`), then add to `~/.codex/config.toml`: + + ```toml + [mcp_servers.comfy-cloud] + url = "https://cloud.comfy.org/mcp" + env_http_headers = { "X-API-Key" = "COMFY_API_KEY" } + ``` + + Set `COMFY_API_KEY` in your shell or system environment. Do not commit the key to version control. + + + + + Any MCP client that supports **remote HTTP** transport can connect to Comfy Cloud. The server URL is always `https://cloud.comfy.org/mcp`. + + + + Add a remote MCP entry pointing at `https://cloud.comfy.org/mcp`. Most clients use a JSON config with a `url` field: + + ```json + { + "mcpServers": { + "comfy-cloud": { + "url": "https://cloud.comfy.org/mcp" + } + } + } + ``` + + **Windsurf** uses `serverUrl` instead of `url`. **Amp** uses the same `mcpServers` shape in **Settings → MCP Servers** or `~/.config/amp/settings.json`. + + + If your client supports MCP OAuth, sign in through the browser when prompted. Otherwise, add an API key header (see below). + + + Restart your client. You should see Comfy Cloud tools (`search_templates`, `submit_workflow`, `get_output`, and others) registered under the **comfy-cloud** server. + + + + **Headless / CI (API key):** when OAuth is not available, create a key at [platform.comfy.org/profile/api-keys](https://platform.comfy.org/profile/api-keys) and pass it as the `X-API-Key` header: + + ```json + { + "mcpServers": { + "comfy-cloud": { + "url": "https://cloud.comfy.org/mcp", + "headers": { + "X-API-Key": "comfyui-…" + } + } + } + } + ``` + + For Claude Code from the terminal: + + ```bash + claude mcp add --transport http comfy-cloud https://cloud.comfy.org/mcp -H "X-API-Key: comfyui-…" + ``` + + Prefer `${env:COMFY_API_KEY}` or your client's secret interpolation instead of hard-coding keys in config files you commit to git. + + ## What your agent can do @@ -116,136 +403,6 @@ Tools that spend real money are **spend-gated**. When a generation uses a paid p You can ask your agent about your balance at any time ("how many credits do I have?") — it answers via `get_billing_status`. -## Install - -Pick your client: - - - - Install the plugin. Connection and commands in one step. - - - Add a custom connector in the app, then sign in. - - - -### Claude Code - -Install the **comfy-cloud** plugin. It adds the MCP connection and the slash commands in one step. The plugin is published through the [Comfy Skills](https://github.com/Comfy-Org/comfy-skills/) repository, which hosts Claude Code plugins and community agent skills for Comfy. - - - - Register the Comfy Skills marketplace (one-time): - - ``` - /plugin marketplace add Comfy-Org/comfy-skills - ``` - - - ``` - /plugin install comfy-cloud@comfy-skills - ``` - - - Run `/mcp`, select **comfy-cloud** → **Authenticate**. Your browser opens to sign in, and tokens refresh automatically. - - - -The plugin adds these slash commands: - -| Command | What it does | -| --- | --- | -| `/comfy-cloud:generate-image` | Generate, edit, or modify an image | -| `/comfy-cloud:generate-video` | Generate, edit, or extend a video | -| `/comfy-cloud:generate-audio` | Generate audio, music, or sound effects | -| `/comfy-cloud:generate-3d` | Generate a 3D model from text or an image | -| `/comfy-cloud:remove-background` | Remove the background from an image | -| `/comfy-cloud:upscale-image` | Upscale an image to higher resolution | -| `/comfy-cloud:search-templates` | Find pre-built workflow templates on [comfy.org](https://comfy.org) | -| `/comfy-cloud:search-models` | Search for available models | -| `/comfy-cloud:search-nodes` | Search for nodes and get wiring suggestions | -| `/comfy-cloud:help` | See what you can do with ComfyUI Cloud | - - - Add the server directly: - - ```bash - claude mcp add --transport http comfy-cloud https://cloud.comfy.org/mcp - ``` - - Then run `/mcp`, select **comfy-cloud** → **Authenticate**. Add `-s user` to make it available in all your projects. - - This path still exposes the same workflows as MCP prompts: `/mcp__comfy-cloud__generate-image`, `/mcp__comfy-cloud__search-models`, and so on (the `/mcp____` prefix uses the name you passed to `claude mcp add`). The plugin above is recommended because it wraps these as the friendlier `/comfy-cloud:*` commands. - - -### Claude Desktop - -Claude Desktop adds Comfy Cloud as a **custom connector** through its UI, then runs the OAuth sign-in. - - - - - - In Claude Desktop, open **Customize**, then choose **Connectors**. - - ![Claude Desktop Connectors](/images/cloud/mcp/desktop-connectors.png) - - - Click the **+** button, then choose **Add custom connector**. - - ![Add custom connector](/images/cloud/mcp/desktop-add-custom-connector.png) - - - Name it anything (for example, *Comfy Cloud*) and set the **Remote MCP server URL** to: - - ``` - https://cloud.comfy.org/mcp - ``` - - ![Connector details](/images/cloud/mcp/desktop-connector-url.png) - - - Click **Add**, then sign in through Claude Desktop when prompted. You are connected. - - ![Sign in through Claude Desktop](/images/cloud/mcp/desktop-signin.png) - - - -Claude Desktop does not support Claude Code slash commands. Instead, open the **prompt picker** for the same workflows: - -| Prompt | Description | -| --- | --- | -| `generate-image` | Generate an image from a text description | -| `generate-video` | Generate a video from text or an image | -| `generate-audio` | Generate audio, music, or sound effects | -| `generate-3d` | Generate a 3D model from text or an image | -| `upscale-image` | Upscale an image to higher resolution | -| `remove-background` | Remove the background from an image | -| `search-templates` | Find pre-built workflow templates | -| `search-models` | Search for models (checkpoints, LoRAs, VAEs) | -| `search-nodes` | Search nodes and get wiring suggestions | -| `help` | See what you can do with ComfyUI Cloud | - -You can also skip prompts and ask in plain language. The MCP tools work the same way. - -### Headless / CI (API key) - -Claude Code and Claude Desktop use OAuth, so you do not need an API key. For **headless or CI** setups where no browser is available, authenticate with an API key instead: - - - - Go to [platform.comfy.org/profile/api-keys](https://platform.comfy.org/profile/api-keys), click **New API Key**, and copy it (it starts with `comfyui-`). - - - ```bash - claude mcp add --transport http comfy-cloud https://cloud.comfy.org/mcp -H "X-API-Key: comfyui-…" - ``` - - ## Outputs and downloads @@ -300,10 +457,10 @@ Comfy Cloud MCP is an early release. These limitations are known and being worke - Claude Code and Claude Desktop today, both signing in with OAuth. Support for more clients is coming. + Any MCP-compatible client that supports remote HTTP transport can connect to `https://cloud.comfy.org/mcp`. We document first-class setup for **Claude Code**, **Claude Desktop**, **Cursor**, and **Codex**. **Windsurf**, **Amp**, **OpenClaw**, and other agents follow the same URL with OAuth or an API key. See [Install Comfy Cloud MCP](#install-comfy-cloud-mcp). - Not for Claude Code or Claude Desktop. They use OAuth. An API key is only needed for headless or CI setups with no browser. + Not for interactive clients that support OAuth (Claude Code, Claude Desktop, Cursor, Codex, and others). An API key is only needed for headless or CI setups with no browser. See the **Other clients** tab under [Install Comfy Cloud MCP](#install-comfy-cloud-mcp). Paid generations are spend-gated: when a run would consume Comfy Cloud credits (a partner model, or a workflow/template with paid API nodes), the server requires your explicit agreement before executing. See [Credits and spending](#credits-and-spending). diff --git a/images/agent_tools/CodeX_Oauth_mcp.mp4 b/images/agent_tools/CodeX_Oauth_mcp.mp4 new file mode 100644 index 000000000..074d5557b Binary files /dev/null and b/images/agent_tools/CodeX_Oauth_mcp.mp4 differ diff --git a/images/agent_tools/auth.png b/images/agent_tools/auth.png new file mode 100644 index 000000000..9f9d991a6 Binary files /dev/null and b/images/agent_tools/auth.png differ diff --git a/images/agent_tools/claude_desktop_mcp_setup_step1.png b/images/agent_tools/claude_desktop_mcp_setup_step1.png new file mode 100644 index 000000000..01442547e Binary files /dev/null and b/images/agent_tools/claude_desktop_mcp_setup_step1.png differ diff --git a/images/agent_tools/claude_desktop_mcp_setup_step2.png b/images/agent_tools/claude_desktop_mcp_setup_step2.png new file mode 100644 index 000000000..f81a34680 Binary files /dev/null and b/images/agent_tools/claude_desktop_mcp_setup_step2.png differ diff --git a/images/agent_tools/claude_desktop_mcp_setup_step3.png b/images/agent_tools/claude_desktop_mcp_setup_step3.png new file mode 100644 index 000000000..ca2050e12 Binary files /dev/null and b/images/agent_tools/claude_desktop_mcp_setup_step3.png differ diff --git a/images/agent_tools/claude_desktop_mcp_setup_step4.png b/images/agent_tools/claude_desktop_mcp_setup_step4.png new file mode 100644 index 000000000..1486f44b8 Binary files /dev/null and b/images/agent_tools/claude_desktop_mcp_setup_step4.png differ diff --git a/images/agent_tools/codex_mcp_setup_step1.png b/images/agent_tools/codex_mcp_setup_step1.png new file mode 100644 index 000000000..37cd4de31 Binary files /dev/null and b/images/agent_tools/codex_mcp_setup_step1.png differ diff --git a/images/agent_tools/codex_mcp_setup_step2.png b/images/agent_tools/codex_mcp_setup_step2.png new file mode 100644 index 000000000..b17396ce0 Binary files /dev/null and b/images/agent_tools/codex_mcp_setup_step2.png differ diff --git a/images/agent_tools/codex_mcp_setup_step3.png b/images/agent_tools/codex_mcp_setup_step3.png new file mode 100644 index 000000000..e4cd9440b Binary files /dev/null and b/images/agent_tools/codex_mcp_setup_step3.png differ diff --git a/images/agent_tools/codex_mcp_setup_step4.png b/images/agent_tools/codex_mcp_setup_step4.png new file mode 100644 index 000000000..64905ca5d Binary files /dev/null and b/images/agent_tools/codex_mcp_setup_step4.png differ diff --git a/ja/agent-tools/cloud.mdx b/ja/agent-tools/cloud.mdx index e16a2a71b..90385c3df 100644 --- a/ja/agent-tools/cloud.mdx +++ b/ja/agent-tools/cloud.mdx @@ -1,22 +1,22 @@ --- title: "Comfy Cloud MCP" sidebarTitle: "Cloud MCP" -description: "Comfy Cloud MCP サーバー経由で Claude Code と Claude Desktop から Comfy Cloud を利用: 画像・動画・音声・3D の生成、モデルとノードの検索、ワークフローの実行。" +description: "Claude Code、Claude Desktop、Cursor、Codex、またはMCP互換エージェントからComfy Cloud MCPに接続: 画像・ビデオ・オーディオ・3Dの生成、モデルとノードの検索、ワークフローの実行。" icon: "cloud" -translationSourceHash: 8e911aa0 +translationSourceHash: 2c8d585c translationFrom: agent-tools/cloud.mdx translationBlockHashes: "_intro": b1c56a40 - "Overview": 48a88d56 + "Overview": 4b68a7b5 + "Install Comfy Cloud MCP": b6975c91 "What your agent can do": 2c2a22e6 "MCP tools": a9211dee "Credits and spending": 20e94ef0 - "Install": 445ca642 "Outputs and downloads": a2c8c12f "Related resources": 58e75560 "Feedback": 6872768e "Known limitations": 52477743 - "FAQ": 7b3bdcef + "FAQ": 4e76854d --- import CloudFeature from '/snippets/ja/cloud-feature.mdx' @@ -32,233 +32,394 @@ import CloudFeature from '/snippets/ja/cloud-feature.mdx' サーバーは `cloud.comfy.org/mcp` でリモート実行されます。ワークフローは Comfy Cloud の GPU 上で実行されるため、ローカル GPU は不要です。エージェントは HTTPS 経由でサーバーと通信し、サーバーはツール呼び出しを認証済みのリクエストとして Comfy Cloud に代行送信します。 -現在のサポート範囲は **Claude Code** と **Claude Desktop** に限定されており、どちらも **OAuth**（ブラウザで一度きりのログイン）でログインします。今後、他のクライアントにも対応予定です。 +MCP 互換のクライアントはいずれも同じサーバー URL に接続できます。**Claude Code**、**Claude Desktop**、**Cursor**、**Codex** については、以下にファーストクラスのセットアップ手順があります。**Windsurf**、**Amp**、およびその他のエージェントは、OAuth または APIキーを使用して同じ URL から利用できます。 -## エージェントにできること + -MCPツールを自分で呼び出す必要はありません。エージェントがあなたの指示に基づいて適切なツールを選択します。スラッシュコマンドやプロンプト（後述）は、エージェントを一般的なタスクに誘導するショートカットですが、プレーンな言葉でも機能します（「猫の宇宙飛行士の画像を生成して」「この写真をアップスケールして」「Wan 2.2のビデオテンプレートを探して」など）。 +## Comfy Cloud MCP のインストール + + + 接続する前に[Comfy Cloud](https://cloud.comfy.org)アカウントが必要です。まだお持ちでない場合は[サインアップ](https://cloud.comfy.org)してください。セットアップ時のOAuthログインはComfyアカウントを使用します。 + + +Comfy Cloud MCPは以下で実行されます： + +``` +https://cloud.comfy.org/mcp +``` + +クライアントを選択: + + + + **comfy-cloud**プラグインをインストールします。これにより、MCP接続とスラッシュコマンドが一度に追加されます。このプラグインは、[Comfy Skills](https://github.com/Comfy-Org/comfy-skills/)リポジトリを通じて公開されています。このリポジトリにはClaude CodeプラグインとComfy向けのコミュニティエージェントスキルがホストされています。 + + + + Comfy Skillsマーケットプレイスを登録します（1回のみ）： + + ``` + /plugin marketplace add Comfy-Org/comfy-skills + ``` + + + ``` + /plugin install comfy-cloud@comfy-skills + ``` + + + `/mcp`を実行し、**comfy-cloud** → **認証**を選択します。ブラウザが開いてログインし、トークンは自動的に更新されます。 + + + + このプラグインは以下のスラッシュコマンドを追加します： + + | コマンド | 説明 | + | --- | --- | + | `/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でできることを確認 | + + + サーバーを直接追加： + + ```bash + claude mcp add --transport http comfy-cloud https://cloud.comfy.org/mcp + ``` + + その後、`/mcp`を実行し、**comfy-cloud** → **認証**を選択します。`-s user`を追加すると、すべてのプロジェクトで利用可能になります。 + + この方法でも、MCPプロンプトとして同じワークフローが公開されます：`/mcp__comfy-cloud__generate-image`、`/mcp__comfy-cloud__search-models`など（`/mcp__<名前>__`プレフィックスは、`claude mcp add`に渡した名前を使用します）。上記のプラグインは、これらをより親しみやすい`/comfy-cloud:*`コマンドとしてラップするため、推奨されます。 + + + + + Claude Desktopは、UIを通じてComfy Cloudを**カスタムコネクタ**として追加し、OAuthログインを実行します。 + + + + + + サイドバーで**カスタマイズ**（ラベル**1**）をクリックします。 + + ![Claude Desktop — カスタマイズを開く](/images/agent_tools/claude_desktop_mcp_setup_step1.png) + + + **コネクタ**（ラベル**2**）をクリックします。 + + ![Claude Desktop — コネクタを開く](/images/agent_tools/claude_desktop_mcp_setup_step2.png) + + + 1. コネクタヘッダーの**+**ボタン（ラベル**3**）をクリックします。 + 2. **カスタムコネクタを追加**（ラベル**4**）を選択します。 + + ![Claude Desktop — カスタムコネクタを追加](/images/agent_tools/claude_desktop_mcp_setup_step3.png) + + + 1. **名前**フィールド（ラベル**5**）に、**Comfy Cloud MCP**などの名前を入力します。 + 2. **Remote MCP server URL**を`https://cloud.comfy.org/mcp`に設定します（ラベル**6**）。 + 3. **追加**（ラベル**7**）をクリックします。 + + ![Claude Desktop — コネクタの詳細](/images/agent_tools/claude_desktop_mcp_setup_step4.png) + + + 1. ブラウザが開いたら、ワークスペースを選択します（例：**個人ワークスペース**）。 + 2. **続ける**をクリックしてコネクタを承認します。接続されます。 + + ![Comfy Cloud MCP認証](/images/agent_tools/auth.png) + + + + Claude DesktopはClaude Codeのスラッシュコマンドをサポートしていません。代わりに、同じワークフローに対して**プロンプトピッカー**を開きます： + + | プロンプト | 説明 | + | --- | --- | + | `generate-image` | テキスト説明から画像を生成 | + | `generate-video` | テキストまたは画像から動画を生成 | + | `generate-audio` | オーディオ、音楽、効果音を生成 | + | `generate-3d` | テキストまたは画像から3Dモデルを生成 | + | `upscale-image` | 画像を高解像度にアップスケール | + | `remove-background` | 画像から背景を削除 | + | `search-templates` | 事前構築されたワークフローテンプレートを検索 | + | `search-models` | モデル（チェックポイント、LoRA、VAE）を検索 | + | `search-nodes` | ノードを検索し、配線の提案を取得 | + | `help` | ComfyUI Cloudでできることを確認 | + + プロンプトをスキップして、平易な言語で質問することもできます。MCPツールは同様に機能します。 + + + + CursorはリモートMCPサーバーにHTTPで接続します。**Cursor Settings → Tools & MCP**でComfy Cloudを追加するか、MCP設定ファイルを直接編集します。 + + + + プロジェクト内に`.cursor/mcp.json`を作成または編集するか、グローバル設定として`~/.cursor/mcp.json`を作成します： + + ```json + { + "mcpServers": { + "comfy-cloud": { + "url": "https://cloud.comfy.org/mcp" + } + } + } + ``` + + + **Cursor Settings → Tools & MCP**を開きます。**comfy-cloud**を選択し、**Connect**をクリックしてブラウザからログインします（OAuth）。トークンは自動的に更新されます。 + + + 平易な言葉で質問します（「猫の宇宙飛行士の画像を生成して」「Wan 2.2の動画テンプレートを探して」）。Cursorがあなたに代わってMCPツールを呼び出します。 + + + + + ブラウザが利用できない場合は、`X-API-Key`ヘッダーにComfy Cloud APIキーを渡します。[platform.comfy.org/profile/api-keys](https://platform.comfy.org/profile/api-keys)でキーを作成します（`comfyui-`で始まります）： + + ```json + { + "mcpServers": { + "comfy-cloud": { + "url": "https://cloud.comfy.org/mcp", + "headers": { + "X-API-Key": "${env:COMFY_API_KEY}" + } + } + } + } + ``` + + シェルまたはシステム環境に`COMFY_API_KEY`を設定します。キーをバージョン管理にコミットしないでください。 + + + + + [Codex](https://developers.openai.com/codex/cli)は、Streamable HTTPを介してComfy Cloudに接続します。設定でサーバーを追加し、OAuthでログインします。 + + + + + + 1. *Logged in with API key*の下にある**設定**（ラベル**1**）をクリックします。 + 2. **設定**（ラベル**2**）をクリックして、設定パネル全体を開きます。 + + ![Codex設定パネル — ステップ1](/images/agent_tools/codex_mcp_setup_step1.png) + + + 1. 設定リストの**MCPサーバー**（ラベル**3**）をクリックします。 + 2. **+ サーバーを追加**（ラベル**4**）をクリックして、新しいMCPサーバーを追加します。 + + ![Codex MCPサーバー — ステップ2](/images/agent_tools/codex_mcp_setup_step2.png) + + + 1. 接続タイプとして**Streamable HTTP**を選択します。 + 2. **名前**フィールド（ラベル**5**）に**Comfy Cloud MCP**などの名前を入力します。 + 3. **URL**フィールド（ラベル**6**）に`https://cloud.comfy.org/mcp`を入力します。 + 4. **保存**（ラベル**7**）をクリックします。 + + ![Codex MCPサーバー追加 — ステップ3](/images/agent_tools/codex_mcp_setup_step3.png) + + + 1. 保存したサーバーエントリで**認証**（ラベル**8**）をクリックします。 + + ![Codex MCPサーバー認証 — ステップ4](/images/agent_tools/codex_mcp_setup_step4.png) + + 2. ブラウザのポップアップでワークスペースを選択し、**続ける**をクリックしてログインを完了します。接続されます。 + + ![Comfy Cloud MCP認証](/images/agent_tools/auth.png) + + + + 平易な言葉で質問します（「猫の宇宙飛行士の画像を生成して」「Wan 2.2の動画テンプレートを探して」）。Codexがあなたに代わってMCPツールを呼び出します。 + + + ターミナルから登録してログイン： + + ```bash + codex mcp add comfy-cloud --url https://cloud.comfy.org/mcp + codex mcp login comfy-cloud + ``` + + これにより、`~/.codex/config.toml`（または信頼するプロジェクトの`.codex/config.toml`）にエントリが書き込まれます。 + + + + ブラウザが利用できない場合は、環境変数からヘッダーを取得するサーバーを追加します。[platform.comfy.org/profile/api-keys](https://platform.comfy.org/profile/api-keys)でキーを作成し（`comfyui-`で始まります）、`~/.codex/config.toml`に追加します： + + ```toml + [mcp_servers.comfy-cloud] + url = "https://cloud.comfy.org/mcp" + env_http_headers = { "X-API-Key" = "COMFY_API_KEY" } + ``` + + シェルまたはシステム環境に`COMFY_API_KEY`を設定します。キーをバージョン管理にコミットしないでください。 + + + + + **リモートHTTP**トランスポートをサポートするMCPクライアントは、Comfy Cloudに接続できます。サーバーURLは常に`https://cloud.comfy.org/mcp`です。 + + + + `https://cloud.comfy.org/mcp`を指すリモートMCPエントリを追加します。ほとんどのクライアントは`url`フィールドを持つJSON設定を使用します： + + ```json + { + "mcpServers": { + "comfy-cloud": { + "url": "https://cloud.comfy.org/mcp" + } + } + } + ``` + + **Windsurf**は`url`の代わりに`serverUrl`を使用します。**Amp**は**Settings → MCP Servers**または`~/.config/amp/settings.json`で同じ`mcpServers`構造を使用します。 + + + クライアントがMCP OAuthをサポートしている場合は、ブラウザからログインします。それ以外の場合は、APIキーヘッダーを追加します（下記参照）。 + + + クライアントを再起動します。**comfy-cloud**サーバーにComfy Cloudツール（`search_templates`、`submit_workflow`、`get_output`など）が登録されているはずです。 + + + + **ヘッドレス/CI（APIキー）：** OAuthが利用できない場合は、[platform.comfy.org/profile/api-keys](https://platform.comfy.org/profile/api-keys)でキーを作成し、`X-API-Key`ヘッダーとして渡します： + + ```json + { + "mcpServers": { + "comfy-cloud": { + "url": "https://cloud.comfy.org/mcp", + "headers": { + "X-API-Key": "comfyui-…" + } + } + } + } + ``` + + ターミナルからClaude Codeを使用する場合： + + ```bash + claude mcp add --transport http comfy-cloud https://cloud.comfy.org/mcp -H "X-API-Key: comfyui-…" + ``` + + 設定ファイルにキーを直接記述するのではなく、`${env:COMFY_API_KEY}`またはクライアントのシークレット補間を使用することをお勧めします（gitにコミットする設定ファイルで）。 + + + + +## エージェントができること + +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`が、エージェントがシェルで実行するダウンロードコマンドを返します。 +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)とのマッチングを優先します。これにより、より速く良い結果が得られる傾向があります。 +サーバーは、ワークフローをゼロから構築する前に、[事前構築済みテンプレート](https://comfy.org/workflows)を優先してマッチングします。これにより、より速く、より良い結果が得られる傾向があります。 ## MCP ツール -以下はエージェントが接続後にアクセスできるツールです。名前は MCP クライアントのログやデバッグに表示されるものと一致します。 +これらは、エージェントが接続後にアクセスできるツールです。名前は MCP クライアントのログやデバッグに表示されるものと一致します。 ### 検索 | ツール | 説明 | | --- | --- | -| `search_templates` | [comfy.org](https://comfy.org/workflows) から、テキスト、タグ、メディア種類、モデルで事前構築済みワークフローテンプレートを検索します。 | -| `get_template` | テンプレートの完全なワークフロー JSON を取得し、検査や手動編集に利用します。 | -| `get_template_schema` | テンプレートのどのパラメータが実行時にオーバーライド可能かを確認します。 | -| `search_models` | モデルカタログをテキスト、種類、ベースモデル、ソースで検索します。 | -| `search_nodes` | 利用可能なノードをテキスト、カテゴリ、入出力タイプで検索します。また、**サブグラフブループリント**（テキストから画像へ、背景を削除 など、あらかじめ配線されたノードグループ）も表示します。 | -| `get_node` | 特定ノードの完全な入力仕様（全オプションリストを含む）を取得します。 | -| `cql` | 構造的な質問（例：どのノードが画像を生成するか、ノードタイプ間のパスなど）に対して [CQL](https://github.com/Comfy-Org/cql) グラフクエリを実行します。特定ノードの完全な入力仕様が必要な場合は `search_nodes` を使用してください。 | -| `get_prompting_guide` | モデルファミリーごとのプロンプトスタイルと推奨設定（steps、cfg、sampler、解像度）を取得します。 | +| `search_templates` | [comfy.org](https://comfy.org/workflows) からテキスト、タグ、メディアタイプ、またはモデルで事前構築済みのワークフローテンプレートを検索します | +| `get_template` | テンプレートの完全なワークフロー JSON を取得し、検査や手動編集を行えます | +| `get_template_schema` | テンプレートのどのパラメータが実行時にオーバーライド可能かを確認します | +| `search_models` | テキスト、タイプ、ベースモデル、またはソースでモデルカタログを検索します | +| `search_nodes` | テキスト、カテゴリ、入力/出力タイプで利用可能なノードを検索します。また、**サブグラフブループリント**（テキストから画像へや背景を削除などの事前配線済みノードグループ）も表示します | +| `get_node` | 特定のノードの完全な入力仕様を取得します（全オプションリストを含む） | +| `cql` | 構造的な質問を行うために [CQL](https://github.com/Comfy-Org/cql) グラフクエリを実行します（例：どのノードが画像を生成するか、ノードタイプ間のパスなど）。特定のノードの完全な入力仕様が必要な場合は `search_nodes` を使用してください | +| `get_prompting_guide` | モデルファミリーごとのプロンプトスタイルと推奨設定（ステップ数、CFG、サンプラー、解像度） | ### 生成 | ツール | 説明 | | --- | --- | -| `run_template` | 事前構築済みテンプレートを名前で実行します（オプションでパラメータのオーバーライドが可能）。テンプレートが一致する場合はこちらが推奨される方法です。 | -| `submit_workflow` | ComfyUI API 形式のワークフローを Comfy Cloud で実行するために送信します。 | -| `partner_generate` | パートナー API モデル（Flux/BFL、Grok、Gemini、OpenAI、Ideogram、Seedream/Seedance など）で生成します。 | -| `upload_file` | ワークフローで使用する入力画像やファイルをアップロードします（例：LoadImage ノード用）。 | -| `apply_slots` | ワークフロー内部の値にパラメータオーバーライドを適用し、変更後のワークフローを返します。 | +| `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` | 多数の生成を1回の呼び出しで送信し、後でまとめて回収します。バッチ ID はセッションをまたいで有効です。 | +| `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` | 保存済みワークフローをファイル名で実行します。サーバーがエディタ形式から実行可能形式へ自動的に変換します。 | +| `list_saved_workflows` | Comfy Cloud に保存されたワークフローをブラウズします | +| `get_saved_workflow` | 保存済みワークフローのノード、入力、カスタマイズ可能な設定を検査します | +| `save_workflow` | ワークフローを Comfy Cloud アカウントに保存します | +| `update_workflow` | 既存のワークフローを新しいバージョンとしてその場で更新します（以前のバージョンは復元可能なまま保持されます） | +| `run_saved_workflow` | ファイル名を指定して保存済みワークフローを実行します。サーバーがエディタ形式から実行可能形式に自動変換します | ### ワークフローの共有 | ツール | 説明 | | --- | --- | -| `share_workflow` | 保存済みワークフローを公開し、誰でも開ける `?share=` URL を返します。 | -| `import_shared_workflow` | 共有 URL または bare な共有 ID を解決してワークフロー JSON を取得し、オプションでアカウントに保存します。 | +| `share_workflow` | 保存済みワークフローを公開し、誰でも開ける `?share=` URL を返します | +| `import_shared_workflow` | 共有 URL または共有 ID をワークフロー JSON に解決し、オプションでアカウントに保存します | -**ハブ URL の共有 ID:** `comfy.org/workflows/-` のようなハブ URL 内の末尾のハイフン区切り16進トークンが共有 ID です。例えば、`comfy.org/workflows/topaz-starlight-upscale-1c77e82713b7` の共有 ID は `1c77e82713b7` です。このトークンを `import_shared_workflow` の `share_id` に渡してください。`share_url` パラメータは `?share=` クエリ形式の URL（例：`https://cloud.comfy.org/?share=...`）のみを受け付け、ハブページ URL は受け付けません。 +**Hub URL 共有 ID：** `comfy.org/workflows/-` ハブ URL 内の末尾のハイフン区切り16進トークンが共有 ID です。たとえば、`comfy.org/workflows/topaz-starlight-upscale-1c77e82713b7` の共有 ID は `1c77e82713b7` です。そのトークンを `share_id` として `import_shared_workflow` に渡します。`share_url` パラメータは `https://cloud.comfy.org/?share=...` のような `?share=` クエリ URL のみを受け付け、ハブページ URL は受け付けません。 ### アプリとリンク | ツール | 説明 | | --- | --- | -| `create_app` | 保存済みワークフローを App Mode アプリに変換します。選択した入力と出力だけを備えた、シンプルな「このワークフローを実行する」ビューです。 | -| `get_app_mode_url` | ワークフローを実行可能なアプリとして開く、安定したリンクを取得します。 | -| `get_workflow_canvas_url` | ワークフローを Comfy Cloud のキャンバス上で直接開くリンクを取得します。そのまま閲覧、編集、実行できます。 | +| `create_app` | 保存済みワークフローをアプリモードのアプリに変換します。選択した入力と出力を持つ簡略化された「このワークフローを実行」ビューです | +| `get_app_mode_url` | ワークフローを実行可能なアプリとして開く安定したリンクを取得します | +| `get_workflow_canvas_url` | ワークフローを直接 Comfy Cloud のキャンバスで開き、表示、編集、実行できるリンクを取得します | ### アカウントとセッション | ツール | 説明 | | --- | --- | -| `get_billing_status` | クレジット残高、サブスクリプションのプラン、請求リンクを確認します。 | -| `get_server_info` | エージェントが接続したサーバーを確認します（環境、ホスト、バージョン、認証状態）。 | -| `submit_feedback` | ベータ版フィードバックアンケートのリンクを取得します。 | -| `report_session_summary` | 匿名化されたセッションサマリーを Comfy チームに共有します — **明示的な同意がある場合のみ**。エージェントは必ず事前に確認し、プロンプト、ファイルパス、個人情報は含まれません。 | - -## クレジットと支出 - -検索は無料です：`search_templates`、`search_models`、`search_nodes` は [Comfy アカウント](https://cloud.comfy.org) だけで利用できます。生成の実行は Comfy Cloud のクレジットを消費し、サブスクリプションまたはクレジット残高が必要です。 - -実際にお金を消費するツールは**支出ゲート（spend-gated）**の対象です。生成が有料のパートナーモデル（`partner_generate`）や、有料 API ノードを含むワークフロー/テンプレート（`run_template`、`run_saved_workflow`、`submit_batch`）を使用する場合、サーバーは、クレジットの消費にあなたが同意したことをエージェントが確認するまで実行をブロックします。そのため、これらの実行前にはエージェントから確認を求められます。有料 API ノードを含まない無料のローカル実行のみのワークフローで確認が求められることはありません。 - -残高はいつでもエージェントに尋ねられます（「クレジットはいくら残っている？」など）。エージェントは `get_billing_status` を使って回答します。 - -## インストール - -クライアントを選択してください: - - - - プラグインをインストールします。接続とコマンドがワンステップで完了します。 - - - アプリでカスタムコネクターを追加し、ログインします。 - - - -### Claude Code - -**comfy-cloud** プラグインをインストールします。MCP接続とスラッシュコマンドをワンステップで追加します。このプラグインは、Claude CodeプラグインとComfy用のコミュニティエージェントスキルをホストする [Comfy Skills](https://github.com/Comfy-Org/comfy-skills/) リポジトリを通じて公開されています。 - - - - Comfy Skillsマーケットプレイスを登録します（一度だけ）: - - ``` - /plugin marketplace add Comfy-Org/comfy-skills - ``` - - - ``` - /plugin install comfy-cloud@comfy-skills - ``` - - - `/mcp` を実行し、**comfy-cloud** → **Authenticate** を選択します。ブラウザが開いてログインし、トークンは自動的に更新されます。 - - - -このプラグインは以下のスラッシュコマンドを追加します: - -| コマンド | 機能 | -| --- | --- | -| `/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 でできることを確認します | - - - サーバーを直接追加します: - - ```bash - 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____` プレフィックスは `claude mcp add` に渡した名前を使用します）。上記のプラグインは、これらをより使いやすい `/comfy-cloud:*` コマンドとしてラップするため、推奨されます。 - - -### Claude Desktop +| `get_billing_status` | あなたのクレジット残高、サブスクリプション階層、請求リンクを確認します | +| `get_server_info` | エージェントが到達したサーバーを確認します（環境、ホスト、バージョン、認証状態） | +| `submit_feedback` | ベータ版フィードバック調査のリンクを取得します | +| `report_session_summary` | 匿名化されたセッションサマリーを Comfy チームと共有します。**あなたの明示的な同意がある場合のみ**。エージェントは事前に許可を求める必要があり、プロンプト、ファイルパス、個人情報は含まれません | -Claude Desktopは、UIを通じてComfy Cloudを**カスタムコネクター**として追加し、OAuthログインを実行します。 + - - - - - Claude Desktopで **カスタマイズ** を開き、**コネクター** を選択します。 - - ![Claude Desktop コネクター](/images/cloud/mcp/desktop-connectors.png) - - - **+** ボタンをクリックし、**カスタムコネクターを追加** を選択します。 - - ![カスタムコネクターを追加](/images/cloud/mcp/desktop-add-custom-connector.png) - - - 任意の名前を付け（例: *Comfy Cloud*）、**Remote MCP server URL** を次のように設定します: - - ``` - https://cloud.comfy.org/mcp - ``` - - ![コネクター詳細](/images/cloud/mcp/desktop-connector-url.png) - - - **Add** をクリックし、プロンプトに従ってClaude Desktopからログインします。接続が完了します。 +## クレジットと支出 - ![Claude Desktopからログイン](/images/cloud/mcp/desktop-signin.png) - - +検索は無料です: `search_templates`、`search_models`、`search_nodes` は [Comfy アカウント](https://cloud.comfy.org) だけで動作します。生成の実行は Comfy Cloud のクレジットを消費し、サブスクリプションまたはクレジット残高が必要です。 -Claude DesktopはClaude Codeのスラッシュコマンドをサポートしていません。代わりに、**プロンプトピッカー** を開いて同じワークフローにアクセスします: +実際にお金を使うツールは **出費制限付き** です。生成で有料パートナーモデル (`partner_generate`) や有料 API ノードを含むワークフロー/テンプレート (`run_template`、`run_saved_workflow`、`submit_batch`) を使用する場合、サーバーはエージェントがクレジットを消費することに同意したことを確認するまで実行をブロックします。そのため、それらの実行前にエージェントが確認を求めます。無料のローカルのみのワークフローはプロンプトを表示しません。 -| プロンプト | 説明 | -| --- | --- | -| `generate-image` | テキスト説明から画像を生成 | -| `generate-video` | テキストまたは画像からビデオを生成 | -| `generate-audio` | オーディオ、音楽、または効果音を生成 | -| `generate-3d` | テキストまたは画像から3Dモデルを生成 | -| `upscale-image` | 画像を高解像度にアップスケール | -| `remove-background` | 画像から背景を削除 | -| `search-templates` | 事前構築済みのワークフローテンプレートを検索 | -| `search-models` | モデルを検索（チェックポイント、LoRA、VAE） | -| `search-nodes` | ノードを検索し、配線の提案を取得 | -| `help` | ComfyUI Cloud でできることを確認 | - -プロンプトをスキップして、平易な言葉で質問することもできます。MCPツールは同じように動作します。 - -### ヘッドレス / CI (APIキー) - -Claude CodeとClaude DesktopはOAuthを使用するため、APIキーは必要ありません。ブラウザが利用できない**ヘッドレスまたはCI**環境では、代わりにAPIキーで認証します: - - - - [platform.comfy.org/profile/api-keys](https://platform.comfy.org/profile/api-keys) にアクセスし、**New API Key** をクリックしてコピーします（`comfyui-` で始まります）。 - - - ```bash - claude mcp add --transport http comfy-cloud https://cloud.comfy.org/mcp -H "X-API-Key: comfyui-…" - ``` - - +いつでもエージェントに残高を尋ねることができます（「クレジットはいくつありますか？」）。エージェントは `get_billing_status` を通じて回答します。 ## 出力とダウンロード @@ -313,13 +474,13 @@ Comfy Cloud MCP は初期リリースです。以下の制限事項は既知で - Claude Code と Claude Desktop が現在対応しており、どちらも OAuth でサインインします。さらに多くのクライアントへの対応も予定しています。 + MCP に対応し、リモート HTTP トランスポートをサポートしているクライアントはすべて `https://cloud.comfy.org/mcp` に接続できます。**Claude Code**、**Claude Desktop**、**Cursor**、**Codex** のセットアップ方法を文書化しています。**Windsurf**、**Amp**、**OpenClaw** などの他のエージェントも、同じ URL に OAuth または APIキーで接続します。詳細は [Comfy Cloud MCP のインストール](#install-comfy-cloud-mcp) を参照してください。 - Claude Code や Claude Desktop では不要です。これらは OAuth を使用します。APIキーは、ブラウザがないヘッドレスまたはCI環境でのみ必要です。 + OAuth に対応した対話型クライアント（Claude Code、Claude Desktop、Cursor、Codex など）では不要です。APIキーは、ブラウザがないヘッドレスまたは CI 環境でのみ必要です。詳細は [Comfy Cloud MCP のインストール](#install-comfy-cloud-mcp) の **その他のクライアント** タブを参照してください。 - 有料の生成は支出ゲートの対象です：実行が Comfy Cloud のクレジットを消費する場合（パートナーモデル、または有料 API ノードを含むワークフロー/テンプレート）、サーバーは実行前に明示的な同意を必要とします。詳細は「クレジットと支出」セクションを参照してください。 + 有料の生成は支出ゲートの対象です：実行が Comfy Cloud のクレジットを消費する場合（パートナーモデル、または有料 API ノードを含むワークフロー/テンプレート）、サーバーは実行前に明示的な同意を必要とします。詳細は [クレジットと支出](#credits-and-spending) を参照してください。 いいえ。スラッシュコマンドは Claude Code プラグインに含まれています。Claude Desktop は同じ MCP サーバーに接続します（ツールはプレーン言語で質問するか、プロンプトピッカーを使えば機能します）が、Claude Code プラグインやスラッシュコマンドはサポートしていません。 diff --git a/ko/agent-tools/cloud.mdx b/ko/agent-tools/cloud.mdx index f0c5bc1bf..e00dd412e 100644 --- a/ko/agent-tools/cloud.mdx +++ b/ko/agent-tools/cloud.mdx @@ -1,22 +1,22 @@ --- title: "Comfy Cloud MCP" sidebarTitle: "Cloud MCP" -description: "Claude Code와 Claude Desktop에서 Comfy Cloud를 Comfy Cloud MCP 서버를 통해 사용하세요: 이미지, 비디오, 오디오 및 3D 생성, 모델 및 노드 검색, 워크플로우 실행 가능" +description: "Claude Code, Claude Desktop, Cursor, Codex 또는 MCP 호환 에이전트에서 Comfy Cloud MCP에 연결하여 이미지, 비디오, 오디오 및 3D를 생성하고, 모델과 노드를 검색하며, 워크플로를 실행하세요." icon: "cloud" -translationSourceHash: 8e911aa0 +translationSourceHash: 2c8d585c translationFrom: agent-tools/cloud.mdx translationBlockHashes: "_intro": b1c56a40 - "Overview": 48a88d56 + "Overview": 4b68a7b5 + "Install Comfy Cloud MCP": b6975c91 "What your agent can do": 2c2a22e6 "MCP tools": a9211dee "Credits and spending": 20e94ef0 - "Install": 445ca642 "Outputs and downloads": a2c8c12f "Related resources": 58e75560 "Feedback": 6872768e "Known limitations": 52477743 - "FAQ": 7b3bdcef + "FAQ": 4e76854d --- import CloudFeature from '/snippets/ko/cloud-feature.mdx' @@ -32,233 +32,393 @@ import CloudFeature from '/snippets/ko/cloud-feature.mdx' 서버는 `cloud.comfy.org/mcp`에서 원격으로 실행됩니다. 워크플로는 Comfy Cloud GPU에서 실행되므로 로컬 GPU가 필요하지 않습니다. 에이전트는 HTTPS를 통해 서버와 통신하며, 서버는 도구 호출을 대신 인증된 요청으로 변환하여 Comfy Cloud에 전송합니다. -현재 지원 범위는 **Claude Code**와 **Claude Desktop**에 국한되며, 이들은 **OAuth**(일회성 브라우저 로그인)를 통해 로그인합니다. 더 많은 클라이언트 지원이 곧 제공될 예정입니다. +모든 **MCP 호환 클라이언트**가 동일한 서버 URL에 연결할 수 있습니다. **Claude Code**, **Claude Desktop**, **Cursor**, **Codex**는 아래에 전용 설정 안내가 있습니다. **Windsurf**, **Amp** 및 기타 에이전트는 OAuth 또는 API 키를 사용하여 동일한 URL을 사용합니다. + + + +## Comfy Cloud MCP 설치 + + + 연결하기 전에 [Comfy Cloud](https://cloud.comfy.org) 계정이 필요합니다. 아직 계정이 없다면 [가입하기](https://cloud.comfy.org)를 클릭하세요. 설정 중 OAuth 로그인은 Comfy 계정을 사용합니다. + + +Comfy Cloud MCP는 다음 주소에서 실행됩니다: + +``` +https://cloud.comfy.org/mcp +``` + +클라이언트를 선택하세요: + + + + **comfy-cloud** 플러그인을 설치하세요. 이 플러그인은 MCP 연결과 슬래시 명령어를 한 번에 추가합니다. 이 플러그인은 Comfy의 Claude Code 플러그인과 커뮤니티 에이전트 스킬을 호스팅하는 [Comfy Skills](https://github.com/Comfy-Org/comfy-skills/) 저장소를 통해 게시됩니다. + + + + Comfy Skills 마켓플레이스를 등록합니다(한 번만 수행): + + ``` + /plugin marketplace add Comfy-Org/comfy-skills + ``` + + + ``` + /plugin install comfy-cloud@comfy-skills + ``` + + + `/mcp`를 실행하고 **comfy-cloud** → **Authenticate**를 선택하세요. 브라우저가 열려 로그인하고 토큰은 자동으로 새로 고쳐집니다. + + + + 플러그인은 다음 슬래시 명령어를 추가합니다: + + | 명령어 | 설명 | + | --- | --- | + | `/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로 할 수 있는 작업 확인 | + + + 서버를 직접 추가하세요: + + ```bash + 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__<이름>__` 접두사는 `claude mcp add`에 전달한 이름을 사용합니다). 위 플러그인은 이를 더 친숙한 `/comfy-cloud:*` 명령어로 래핑하므로 권장됩니다. + + + + + Claude Desktop은 Comfy Cloud를 UI를 통해 **사용자 지정 커넥터**로 추가한 다음 OAuth 로그인을 실행합니다. + + + + + + 사이드바에서 **Customize**(**1**로 표시)를 클릭하세요. + + ![Claude Desktop — 사용자 정의 열기](/images/agent_tools/claude_desktop_mcp_setup_step1.png) + + + **Connectors**(**2**로 표시)를 클릭하세요. + + ![Claude Desktop — 커넥터 열기](/images/agent_tools/claude_desktop_mcp_setup_step2.png) + + + 1. 커넥터 헤더에서 **+** 버튼(**3**으로 표시)을 클릭하세요. + 2. **Add custom connector**(**4**로 표시)를 선택하세요. + + ![Claude Desktop — 사용자 지정 커넥터 추가](/images/agent_tools/claude_desktop_mcp_setup_step3.png) + + + 1. **Name** 필드(**5**로 표시)에 **Comfy Cloud MCP**와 같은 이름을 입력하세요. + 2. **Remote MCP server URL**을 `https://cloud.comfy.org/mcp`로 설정하세요(**6**으로 표시). + 3. **Add**(**7**로 표시)를 클릭하세요. + + ![Claude Desktop — 커넥터 세부 정보](/images/agent_tools/claude_desktop_mcp_setup_step4.png) + + + 1. 브라우저가 열리면 워크스페이스(예: **Personal Workspace**)를 선택하세요. + 2. **Continue**를 클릭하여 커넥터를 승인합니다. 연결됩니다. + + ![Comfy Cloud MCP 권한 부여](/images/agent_tools/auth.png) + + + + Claude Desktop은 Claude Code 슬래시 명령어를 지원하지 않습니다. 대신 **프롬프트 선택기**를 열어 동일한 워크플로를 사용하세요: + + | 프롬프트 | 설명 | + | --- | --- | + | `generate-image` | 텍스트 설명에서 이미지 생성 | + | `generate-video` | 텍스트 또는 이미지에서 비디오 생성 | + | `generate-audio` | 오디오, 음악 또는 사운드 효과 생성 | + | `generate-3d` | 텍스트 또는 이미지에서 3D 모델 생성 | + | `upscale-image` | 이미지를 더 높은 해상도로 업스케일 | + | `remove-background` | 이미지에서 배경 제거 | + | `search-templates` | 사전 구축된 워크플로 템플릿 검색 | + | `search-models` | 모델(체크포인트, LoRA, VAE) 검색 | + | `search-nodes` | 노드 검색 및 연결 제안 받기 | + | `help` | ComfyUI Cloud로 할 수 있는 작업 확인 | + + 프롬프트를 건너뛰고 일반 언어로 요청할 수도 있습니다. MCP 도구는 동일하게 작동합니다. + + + + Cursor는 원격 MCP 서버에 HTTP로 연결됩니다. **Cursor Settings → Tools & MCP**에서 Comfy Cloud를 추가하거나 MCP 구성 파일을 직접 편집하세요. + + + + 프로젝트에 `.cursor/mcp.json`을 생성하거나 편집하거나, 전역 설정을 위해 `~/.cursor/mcp.json`을 편집하세요: + + ```json + { + "mcpServers": { + "comfy-cloud": { + "url": "https://cloud.comfy.org/mcp" + } + } + } + ``` + + + **Cursor Settings → Tools & MCP**를 엽니다. **comfy-cloud**를 선택하고 **Connect**를 클릭하여 브라우저를 통해 로그인합니다(OAuth). 토큰은 자동으로 새로 고쳐집니다. + + + 일반 언어로 요청하세요("고양이 우주비행사 이미지 생성", "Wan 2.2 비디오 템플릿 찾기"). Cursor가 대신 MCP 도구를 호출합니다. + + + + + 브라우저를 사용할 수 없는 경우 `X-API-Key` 헤더에 Comfy Cloud API 키를 전달하세요. [platform.comfy.org/profile/api-keys](https://platform.comfy.org/profile/api-keys)에서 키를 생성하세요(`comfyui-`로 시작): + + ```json + { + "mcpServers": { + "comfy-cloud": { + "url": "https://cloud.comfy.org/mcp", + "headers": { + "X-API-Key": "${env:COMFY_API_KEY}" + } + } + } + } + ``` + + `COMFY_API_KEY`를 셸 또는 시스템 환경에 설정하세요. 키를 버전 관리에 커밋하지 마세요. + + + + + [Codex](https://developers.openai.com/codex/cli)는 Streamable HTTP를 통해 Comfy Cloud에 연결합니다. 설정에서 서버를 추가한 다음 OAuth로 로그인하세요. + + + + + + 1. *Logged in with API key* 아래에서 **Settings**(**1**로 표시)를 클릭하세요. + 2. **Settings**(**2**로 표시)를 클릭하여 전체 설정 패널을 엽니다. + + ![Codex 설정 패널 — 1단계](/images/agent_tools/codex_mcp_setup_step1.png) + + + 1. 설정 목록에서 **MCP servers**(**3**으로 표시)를 클릭하세요. + 2. **+ Add server**(**4**로 표시)를 클릭하여 새 MCP 서버를 추가합니다. + + ![Codex MCP 서버 — 2단계](/images/agent_tools/codex_mcp_setup_step2.png) + + + 1. 연결 유형으로 **Streamable HTTP**를 선택하세요. + 2. **Name** 필드(**5**로 표시)에 **Comfy Cloud MCP**와 같은 이름을 입력하세요. + 3. **URL** 필드(**6**으로 표시)에 `https://cloud.comfy.org/mcp`를 입력하세요. + 4. **Save**(**7**로 표시)를 클릭하세요. + + ![Codex MCP 서버 추가 — 3단계](/images/agent_tools/codex_mcp_setup_step3.png) + + + 1. 저장된 서버 항목에서 **Authenticate**(**8**로 표시)를 클릭하세요. + + ![Codex MCP 서버 인증 — 4단계](/images/agent_tools/codex_mcp_setup_step4.png) + + 2. 브라우저 팝업에서 워크스페이스를 선택하고 **Continue**를 클릭하여 로그인을 완료하세요. 연결됩니다. + + ![Comfy Cloud MCP 권한 부여](/images/agent_tools/auth.png) + + + + 일반 언어로 요청하세요("고양이 우주비행사 이미지 생성", "Wan 2.2 비디오 템플릿 찾기"). Codex가 대신 MCP 도구를 호출합니다. + + + 터미널에서 등록 및 로그인: + + ```bash + codex mcp add comfy-cloud --url https://cloud.comfy.org/mcp + codex mcp login comfy-cloud + ``` + + 이렇게 하면 `~/.codex/config.toml`(또는 신뢰할 수 있는 프로젝트의 `.codex/config.toml`)에 항목이 기록됩니다. + + + + 브라우저를 사용할 수 없는 경우 환경 변수에서 가져온 헤더로 서버를 추가하세요. [platform.comfy.org/profile/api-keys](https://platform.comfy.org/profile/api-keys)에서 키를 생성하세요(`comfyui-`로 시작). 그런 다음 `~/.codex/config.toml`에 추가: + + ```toml + [mcp_servers.comfy-cloud] + url = "https://cloud.comfy.org/mcp" + env_http_headers = { "X-API-Key" = "COMFY_API_KEY" } + ``` + + `COMFY_API_KEY`를 셸 또는 시스템 환경에 설정하세요. 키를 버전 관리에 커밋하지 마세요. + + + + + **원격 HTTP** 전송을 지원하는 모든 MCP 클라이언트는 Comfy Cloud에 연결할 수 있습니다. 서버 URL은 항상 `https://cloud.comfy.org/mcp`입니다. + + + + `https://cloud.comfy.org/mcp`를 가리키는 원격 MCP 항목을 추가하세요. 대부분의 클라이언트는 `url` 필드가 있는 JSON 구성을 사용합니다: + + ```json + { + "mcpServers": { + "comfy-cloud": { + "url": "https://cloud.comfy.org/mcp" + } + } + } + ``` + + **Windsurf**는 `url` 대신 `serverUrl`을 사용합니다. **Amp**는 **Settings → MCP Servers** 또는 `~/.config/amp/settings.json`에서 동일한 `mcpServers` 형식을 사용합니다. + + + 클라이언트가 MCP OAuth를 지원하는 경우 브라우저에서 로그인하라는 메시지가 표시됩니다. 그렇지 않으면 API 키 헤더를 추가하세요(아래 참조). + + + 클라이언트를 재시작하세요. **comfy-cloud** 서버 아래에 Comfy Cloud 도구(`search_templates`, `submit_workflow`, `get_output` 등)가 등록된 것을 확인할 수 있습니다. + + + + **헤드리스 / CI (API 키):** OAuth를 사용할 수 없는 경우 [platform.comfy.org/profile/api-keys](https://platform.comfy.org/profile/api-keys)에서 키를 생성하고 `X-API-Key` 헤더로 전달하세요: + + ```json + { + "mcpServers": { + "comfy-cloud": { + "url": "https://cloud.comfy.org/mcp", + "headers": { + "X-API-Key": "comfyui-…" + } + } + } + } + ``` + + 터미널에서 Claude Code의 경우: + + ```bash + claude mcp add --transport http comfy-cloud https://cloud.comfy.org/mcp -H "X-API-Key: comfyui-…" + ``` + + Git에 커밋하는 구성 파일에 키를 하드코딩하는 대신 `${env:COMFY_API_KEY}` 또는 클라이언트의 비밀 변수 보간을 사용하는 것이 좋습니다. + + ## 에이전트가 할 수 있는 작업 -직접 MCP 도구를 호출하지 않습니다. 에이전트가 사용자의 요청에 따라 적합한 도구를 선택합니다. 슬래시 명령어와 프롬프트(아래 참조)는 에이전트를 일반적인 작업으로 안내하는 단축키이지만, 일반 언어로도 작동합니다("고양이 우주비행사 이미지 생성", "이 사진 업스케일", "Wan 2.2 비디오 템플릿 찾기"). +직접 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`이 에이전트가 셸에서 실행하는 다운로드 명령을 반환). +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)을 일치시키는 것을 선호하며, 이는 더 빠르고 나은 결과를 생성하는 경향이 있습니다. +서버는 처음부터 워크플로를 빌드하기 전에 일치하는 [사전 제작된 템플릿](https://comfy.org/workflows)을 선호하며, 이는 더 빠르고 더 나은 결과를 내는 경향이 있습니다. ## MCP 도구 -연결되면 에이전트가 액세스할 수 있는 도구입니다. 이름은 MCP 클라이언트 로그 및 디버깅에 표시되는 것과 일치합니다. +연결된 후 에이전트가 액세스할 수 있는 도구입니다. 이름은 MCP 클라이언트 로그 및 디버깅에 표시되는 것과 일치합니다. -### Discovery +### 탐색 | 도구 | 설명 | | --- | --- | -| `search_templates` | 텍스트, 태그, 미디어 유형 또는 모델로 [comfy.org](https://comfy.org/workflows)의 사전 제작된 워크플로 템플릿 검색 | -| `get_template` | 검사 또는 직접 편집을 위해 템플릿의 전체 워크플로 JSON 가져오기 | -| `get_template_schema` | 실행 시 재정의할 수 있는 템플릿 매개변수 확인 | -| `search_models` | 텍스트, 유형, 베이스 모델 또는 소스로 모델 카탈로그 검색 | -| `search_nodes` | 텍스트, 카테고리 또는 입력/출력 유형으로 사용 가능한 노드 검색. 또한 **서브그래프 블루프린트**(예: 텍스트 → 이미지 또는 배경 제거와 같은 사전 연결된 노드 그룹)를 표시합니다. | -| `get_node` | 전체 옵션 목록을 포함하여 특정 노드의 완전한 입력 사양 가져오기 | -| `cql` | 구조적 질문(예: 어떤 노드가 이미지를 생성하는지, 또는 노드 유형 간의 경로)을 위해 [CQL](https://github.com/Comfy-Org/cql) 그래프 쿼리 실행. 특정 노드에 대한 전체 입력 사양이 필요한 경우 `search_nodes` 사용 | -| `get_prompting_guide` | 모델 계열별 프롬프트 스타일 및 권장 설정(steps, cfg, sampler, 해상도) 확인 | +| `search_templates` | [comfy.org](https://comfy.org/workflows)에서 사전 구축된 워크플로 템플릿을 텍스트, 태그, 미디어 유형 또는 모델별로 검색합니다. | +| `get_template` | 템플릿의 전체 워크플로 JSON을 가져와서 검사하거나 수동으로 편집합니다. | +| `get_template_schema` | 템플릿의 파라미터 중 런타임에 재정의할 수 있는 항목을 확인합니다. | +| `search_models` | 모델 카탈로그를 텍스트, 유형, 베이스 모델 또는 소스별로 검색합니다. | +| `search_nodes` | 사용 가능한 노드를 텍스트, 카테고리, 입력/출력 유형별로 검색합니다. 또한 **서브그래프 블루프린트**(텍스트 기반 이미지 생성 또는 배경 제거와 같은 사전 연결된 노드 그룹)를 표시합니다. | +| `get_node` | 특정 노드에 대한 전체 입력 사양을 가져옵니다(전체 옵션 목록 포함). | +| `cql` | 구조적 질문(예: 이미지를 생성하는 노드 또는 노드 유형 간 경로)을 위해 [CQL](https://github.com/Comfy-Org/cql) 그래프 쿼리를 실행합니다. 특정 노드의 전체 입력 사양이 필요한 경우 `search_nodes`를 사용하세요. | +| `get_prompting_guide` | 모델 제품군별 프롬프트 스타일 및 권장 설정(스텝, CFG, 샘플러, 해상도)을 제공합니다. | -### Generation +### 생성 | 도구 | 설명 | | --- | --- | -| `run_template` | 사전 구축된 템플릿을 이름으로 실행(선택적 매개변수 재정의 가능) — 일치하는 템플릿이 있을 때 선호되는 경로 | -| `submit_workflow` | Comfy Cloud에서 실행할 ComfyUI API 형식 워크플로 제출 | -| `partner_generate` | 파트너 API 모델(Flux/BFL, Grok, Gemini, OpenAI, Ideogram, Seedream/Seedance 등)로 생성 | -| `upload_file` | 워크플로에서 사용할 입력 이미지 또는 파일 업로드(예: LoadImage 사용) | -| `apply_slots` | 워크플로 내부 값에 매개변수 재정의를 적용하고 수정된 워크플로 반환 | +| `run_template` | 이름으로 사전 구축된 템플릿을 실행하며, 선택적으로 파라미터를 재정의할 수 있습니다. 템플릿이 일치할 때 선호되는 방법입니다. | +| `submit_workflow` | Comfy Cloud에서 실행할 ComfyUI API 형식 워크플로를 제출합니다. | +| `partner_generate` | 파트너 API 모델(Flux/BFL, Grok, Gemini, OpenAI, Ideogram, Seedream/Seedance 등)로 생성합니다. | +| `upload_file` | 워크플로에서 사용할 입력 이미지 또는 파일을 업로드합니다(예: LoadImage 사용). | +| `apply_slots` | 워크플로의 내부 값에 파라미터 재정의를 적용하고 수정된 워크플로를 반환합니다. | -### Jobs and batches +### 작업 및 배치 | 도구 | 설명 | | --- | --- | -| `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는 세션 간에도 유효하게 유지됩니다 | +| `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는 세션 간에 유효합니다. | -### Saved workflows +### 저장된 워크플로 | 도구 | 설명 | | --- | --- | -| `list_saved_workflows` | Comfy Cloud에서 저장된 워크플로 찾아보기 | -| `get_saved_workflow` | 저장된 워크플로의 노드, 입력 및 사용자 정의 가능한 설정 검사 | -| `save_workflow` | 워크플로를 Comfy Cloud 계정에 저장 | -| `update_workflow` | 기존 워크플로를 새 버전으로 그 자리에서 업데이트(이전 버전은 복구 가능하게 유지됨) | -| `run_saved_workflow` | 저장된 워크플로를 파일 이름으로 실행 — 서버가 에디터 형식에서 실행 가능한 형식으로 자동 변환 | +| `list_saved_workflows` | Comfy Cloud에서 저장된 워크플로를 찾아봅니다. | +| `get_saved_workflow` | 저장된 워크플로의 노드, 입력 및 사용자 정의 가능한 설정을 검사합니다. | +| `save_workflow` | 워크플로를 Comfy Cloud 계정에 저장합니다. | +| `update_workflow` | 기존 워크플로를 새 버전으로 제자리에서 업데이트합니다(이전 버전은 복구 가능하게 유지됨). | +| `run_saved_workflow` | 파일 이름으로 저장된 워크플로를 실행합니다. 서버가 편집기 형식에서 실행 가능한 형식으로 자동 변환합니다. | -### Sharing workflows +### 워크플로 공유 | 도구 | 설명 | | --- | --- | -| `share_workflow` | 저장된 워크플로를 게시하고 누구나 열 수 있는 `?share=` URL 반환 | -| `import_shared_workflow` | 공유 URL 또는 bare 공유 ID를 워크플로 JSON으로 확인하고 선택적으로 계정에 저장 | +| `share_workflow` | 저장된 워크플로를 게시하고 누구나 열 수 있는 `?share=` URL을 반환합니다. | +| `import_shared_workflow` | 공유 URL 또는 bare 공유 ID를 워크플로 JSON으로 변환하고, 선택적으로 계정에 저장합니다. | -**허브 URL 공유 ID:** `comfy.org/workflows/-` 허브 URL에서 마지막 하이픈으로 구분된 16진수 토큰이 공유 ID입니다. 예를 들어, `comfy.org/workflows/topaz-starlight-upscale-1c77e82713b7`의 공유 ID는 `1c77e82713b7`입니다. 해당 토큰을 `share_id`로 `import_shared_workflow`에 전달하세요. `share_url` 매개변수는 `https://cloud.comfy.org/?share=...`와 같은 `?share=` 쿼리 URL만 허용하며 허브 페이지 URL은 허용하지 않습니다. +**허브 URL 공유 ID:** `comfy.org/workflows/-` 허브 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=` 쿼리 URL만 허용하며, 허브 페이지 URL은 허용하지 않습니다. -### Apps and links +### 앱 및 링크 | 도구 | 설명 | | --- | --- | -| `create_app` | 저장된 워크플로를 App Mode 앱으로 전환 — 선택한 입력과 출력으로 구성된 단순화된 "이 워크플로 실행" 보기 | -| `get_app_mode_url` | 워크플로를 실행 가능한 앱으로 여는 안정적인 링크 가져오기 | -| `get_workflow_canvas_url` | 워크플로를 Comfy Cloud 캔버스에서 바로 열어 보고, 편집하고, 실행할 수 있는 링크 가져오기 | +| `create_app` | 저장된 워크플로를 앱 모드 앱으로 변환합니다. 선택한 입력 및 출력이 있는 단순화된 "이 워크플로 실행" 보기입니다. | +| `get_app_mode_url` | 워크플로를 실행 가능한 앱으로 여는 안정적인 링크를 가져옵니다. | +| `get_workflow_canvas_url` | 워크플로를 Comfy Cloud 캔버스에서 직접 열어서 보고, 편집하거나 실행할 수 있는 링크를 가져옵니다. | -### Account and session +### 계정 및 세션 | 도구 | 설명 | | --- | --- | -| `get_billing_status` | 크레딧 잔액, 구독 등급 및 결제 링크 확인 | -| `get_server_info` | 에이전트가 연결된 서버 확인: 환경, 호스트, 버전 및 인증 상태 | -| `submit_feedback` | 베타 피드백 설문 링크 가져오기 | -| `report_session_summary` | 익명화된 세션 요약을 Comfy 팀과 공유 — **사용자의 명시적 동의가 있을 때만** 실행되며, 에이전트가 먼저 물어봐야 하고 프롬프트, 파일 경로 또는 개인 정보는 포함되지 않습니다 | - -## 크레딧 및 지출 - -탐색은 무료입니다: `search_templates`, `search_models`, `search_nodes`는 [Comfy 계정](https://cloud.comfy.org)만으로 작동합니다. 생성을 실행하면 Comfy Cloud 크레딧이 소모되며 구독 또는 크레딧 잔액이 필요합니다. - -실제 비용이 발생하는 도구에는 **지출 게이트(spend-gate)**가 적용됩니다. 생성에 유료 파트너 모델(`partner_generate`)이나 유료 API 노드가 포함된 워크플로/템플릿(`run_template`, `run_saved_workflow`, `submit_batch`)이 사용되는 경우, 서버는 사용자가 크레딧 지출에 동의했음을 에이전트가 확인할 때까지 실행을 차단합니다. 따라서 해당 실행 전에 에이전트가 사용자에게 확인을 요청합니다. 무료 로컬 전용 워크플로는 확인을 요청하지 않습니다. - -언제든지 에이전트에게 잔액을 물어볼 수 있습니다("크레딧이 얼마나 남았나요?"). 에이전트는 `get_billing_status`를 통해 답변합니다. - -## 설치 - -클라이언트를 선택하세요: - - - - 플러그인을 설치합니다. 연결과 명령이 한 번에 이루어집니다. - - - 앱에서 사용자 정의 커넥터를 추가한 후 로그인합니다. - - - -### Claude Code - -**comfy-cloud** 플러그인을 설치합니다. MCP 연결과 슬래시 명령이 한 번에 추가됩니다. 이 플러그인은 Comfy용 Claude Code 플러그인과 커뮤니티 에이전트 스킬을 호스팅하는 [Comfy Skills](https://github.com/Comfy-Org/comfy-skills/) 저장소를 통해 게시됩니다. - - - - Comfy Skills 마켓플레이스를 등록합니다(한 번만 실행): - - ``` - /plugin marketplace add Comfy-Org/comfy-skills - ``` - - - ``` - /plugin install comfy-cloud@comfy-skills - ``` - - - `/mcp`를 실행하고 **comfy-cloud** → **Authenticate**를 선택합니다. 브라우저가 열려 로그인되며, 토큰은 자동으로 새로 고쳐집니다. - - - -플러그인은 다음 슬래시 명령을 추가합니다: - -| 명령 | 기능 | -| --- | --- | -| `/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로 할 수 있는 작업 확인 | - - - 서버를 직접 추가합니다: - - ```bash - claude mcp add --transport http comfy-cloud https://cloud.comfy.org/mcp - ``` - - 그런 다음 `/mcp`를 실행하고 **comfy-cloud** → **Authenticate**를 선택합니다. `-s user`를 추가하면 모든 프로젝트에서 사용할 수 있습니다. +| `get_billing_status` | 보유 크레딧 잔액, 구독 등급 및 청구 링크를 확인합니다. | +| `get_server_info` | 에이전트가 도달한 서버를 확인합니다: 환경, 호스트, 버전 및 인증 상태. | +| `submit_feedback` | 베타 피드백 설문조사 링크를 가져옵니다. | +| `report_session_summary` | 익명화된 세션 요약을 Comfy 팀과 공유합니다. **명시적인 동의가 있어야만 가능**하며, 에이전트가 먼저 물어봐야 합니다. 프롬프트, 파일 경로 또는 개인 정보는 포함되지 않습니다. | - 이 방법도 동일한 워크플로를 MCP 프롬프트로 노출합니다: `/mcp__comfy-cloud__generate-image`, `/mcp__comfy-cloud__search-models` 등 (`/mcp____` 접두사는 `claude mcp add`에 전달한 이름을 사용합니다). 위의 플러그인이 더 친숙한 `/comfy-cloud:*` 명령으로 감싸 주므로 권장됩니다. - + -### Claude Desktop +## 크레딧 및 사용 -Claude Desktop은 UI를 통해 Comfy Cloud를 **사용자 정의 커넥터**로 추가한 후 OAuth 로그인을 실행합니다. +탐색은 무료입니다: `search_templates`, `search_models`, `search_nodes`는 [Comfy 계정](https://cloud.comfy.org)만 있으면 작동합니다. 생성 실행은 Comfy Cloud 크레딧을 소비하며 구독 또는 크레딧 잔액이 필요합니다. - +실제 비용이 발생하는 도구는 **spend-gated**입니다. 생성이 유료 파트너 모델(`partner_generate`) 또는 유료 API 노드가 포함된 워크플로/템플릿(`run_template`, `run_saved_workflow`, `submit_batch`)을 사용하는 경우, 서버는 에이전트가 크레딧 사용에 동의했음을 확인할 때까지 실행을 차단합니다. 따라서 해당 실행 이전에 에이전트가 사용자에게 확인을 요청할 것입니다. 무료 로컬 전용 워크플로는 절대 확인을 요청하지 않습니다. - - - Claude Desktop에서 **사용자 정의**를 연 다음 **커넥터**를 선택합니다. - - ![Claude Desktop 커넥터](/images/cloud/mcp/desktop-connectors.png) - - - **+** 버튼을 클릭한 다음 **사용자 정의 커넥터 추가**를 선택합니다. - - ![사용자 정의 커넥터 추가](/images/cloud/mcp/desktop-add-custom-connector.png) - - - 원하는 이름을 지정하고(예: *Comfy Cloud*) **원격 MCP 서버 URL**을 다음으로 설정합니다: - - ``` - https://cloud.comfy.org/mcp - ``` - - ![커넥터 세부 정보](/images/cloud/mcp/desktop-connector-url.png) - - - **추가**를 클릭한 다음 메시지가 표시되면 Claude Desktop을 통해 로그인합니다. 연결이 완료됩니다. - - ![Claude Desktop을 통해 로그인](/images/cloud/mcp/desktop-signin.png) - - - -Claude Desktop은 Claude Code 슬래시 명령을 지원하지 않습니다. 대신 동일한 워크플로를 위해 **프롬프트 선택기**를 엽니다: - -| 프롬프트 | 설명 | -| --- | --- | -| `generate-image` | 텍스트 설명에서 이미지 생성 | -| `generate-video` | 텍스트 또는 이미지에서 비디오 생성 | -| `generate-audio` | 오디오, 음악 또는 음향 효과 생성 | -| `generate-3d` | 텍스트 또는 이미지에서 3D 모델 생성 | -| `upscale-image` | 이미지를 더 높은 해상도로 업스케일 | -| `remove-background` | 이미지에서 배경 제거 | -| `search-templates` | 미리 빌드된 워크플로 템플릿 검색 | -| `search-models` | 모델 검색 (체크포인트, LoRA, VAE) | -| `search-nodes` | 노드 검색 및 연결 제안 받기 | -| `help` | ComfyUI Cloud로 할 수 있는 작업 확인 | - -프롬프트를 건너뛰고 일반 언어로 요청할 수도 있습니다. MCP 도구는 동일하게 작동합니다. - -### 헤드리스 / CI (API 키) - -Claude Code와 Claude Desktop은 OAuth를 사용하므로 API 키가 필요하지 않습니다. 브라우저를 사용할 수 없는 **헤드리스 또는 CI** 설정의 경우 대신 API 키로 인증합니다: - - - - [platform.comfy.org/profile/api-keys](https://platform.comfy.org/profile/api-keys)로 이동하여 **New API Key**를 클릭하고 복사합니다(`comfyui-`로 시작). - - - ```bash - claude mcp add --transport http comfy-cloud https://cloud.comfy.org/mcp -H "X-API-Key: comfyui-…" - ``` - - +언제든지 에이전트에게 잔액 정보를 물어볼 수 있습니다("크레딧이 얼마나 있나요?") — `get_billing_status`를 통해 답변합니다. ## 출력 및 다운로드 @@ -313,13 +473,13 @@ Comfy Cloud MCP는 초기 릴리스입니다. 다음 제한 사항이 알려져 - 현재 Claude Code와 Claude Desktop이 지원되며, 둘 다 OAuth로 로그인합니다. 더 많은 클라이언트 지원이 곧 추가될 예정입니다. + 원격 HTTP 전송을 지원하는 모든 MCP 호환 클라이언트는 `https://cloud.comfy.org/mcp`에 연결할 수 있습니다. **Claude Code**, **Claude Desktop**, **Cursor** 및 **Codex**에 대한 일급 설정을 문서화합니다. **Windsurf**, **Amp**, **OpenClaw** 및 기타 에이전트는 OAuth 또는 API 키를 사용하여 동일한 URL을 따릅니다. [Comfy Cloud MCP 설치](#install-comfy-cloud-mcp)를 참조하세요. - Claude Code나 Claude Desktop에서는 필요하지 않습니다. OAuth를 사용합니다. API 키는 브라우저가 없는 헤드리스 또는 CI 환경에서만 필요합니다. + OAuth를 지원하는 대화형 클라이언트(Claude Code, Claude Desktop, Cursor, Codex 등)에는 필요하지 않습니다. API 키는 브라우저 없이 헤드리스 또는 CI 설정에서만 필요합니다. [Comfy Cloud MCP 설치](#install-comfy-cloud-mcp)의 **기타 클라이언트** 탭을 참조하세요. - 유료 생성에는 지출 게이트가 적용됩니다: 실행이 Comfy Cloud 크레딧을 소모하는 경우(파트너 모델 또는 유료 API 노드가 포함된 워크플로/템플릿), 서버는 실행 전에 사용자의 명시적 동의를 요구합니다. 자세한 내용은 위의 크레딧 및 지출 섹션을 참조하세요. + 유료 생성에는 지출 게이트가 적용됩니다: 실행이 Comfy Cloud 크레딧을 소모하는 경우(파트너 모델 또는 유료 API 노드가 포함된 워크플로/템플릿), 서버는 실행 전에 사용자의 명시적 동의를 요구합니다. 자세한 내용은 [크레딧 및 지출](#credits-and-spending)을 참조하세요. 아니요. 슬래시 명령은 Claude Code 플러그인에 포함되어 있습니다. Claude Desktop은 동일한 MCP 서버에 연결됩니다(일반 언어로 요청하거나 프롬프트 선택기를 사용하면 도구가 작동합니다). 하지만 Claude Code 플러그인이나 슬래시 명령은 지원하지 않습니다. @@ -336,6 +496,6 @@ Comfy Cloud MCP는 초기 릴리스입니다. 다음 제한 사항이 알려져 Claude Code에서 `/mcp`를 실행하고 **comfy-cloud**를 **선택**한 다음 **인증**을 선택하세요. Claude Desktop에서는 **사용자 정의 → 커넥터**에서 커넥터를 다시 열고 로그인을 트리거하세요. - Comfy Cloud MCP는 저희가 호스팅하는 서비스이지만, 로컬 에이전트 워크플로는 ComfyUI가 오픈소스화된 이후로 존재해 왔습니다. Agent Tools 개요에서 [로컬 ComfyUI는 어떻습니까?](/ko/agent-tools#what-about-local-comfyui)를 참조하여 클라우드가 먼저 출시된 이유, 현재 사용할 수 있는 커뮤니티 MCP 서버, 그리고 또 다른 옵션으로 [Comfy CLI](/ko/agent-tools/comfy-cli)를 확인하세요. + Comfy Cloud MCP는 당사의 호스팅 서비스이지만, 로컬 에이전트 워크플로는 ComfyUI가 오픈소스화된 이후로 존재해 왔습니다. Agent Tools 개요에서 [로컬 ComfyUI는 어떻습니까?](/ko/agent-tools#what-about-local-comfyui)를 참조하여 클라우드가 먼저 출시된 이유, 현재 사용할 수 있는 커뮤니티 MCP 서버, 그리고 또 다른 옵션인 [Comfy CLI](/ko/agent-tools/comfy-cli)를 확인하세요. diff --git a/zh/agent-tools/cloud.mdx b/zh/agent-tools/cloud.mdx index b2c6f1a29..a7c9e9300 100644 --- a/zh/agent-tools/cloud.mdx +++ b/zh/agent-tools/cloud.mdx @@ -1,22 +1,22 @@ --- title: "Comfy Cloud MCP" sidebarTitle: "Cloud MCP" -description: "通过 Comfy Cloud MCP 服务器，在 Claude Code 和 Claude Desktop 中使用 Comfy Cloud：生成图像、视频、音频和 3D，搜索模型与节点，并运行工作流。" +description: "从 Claude Code、Claude Desktop、Cursor、Codex 或任何兼容 MCP 的代理连接 Comfy Cloud MCP：生成图像、视频、音频和 3D，搜索模型与节点，并运行工作流。" icon: "cloud" -translationSourceHash: 8e911aa0 +translationSourceHash: 2c8d585c translationFrom: agent-tools/cloud.mdx translationBlockHashes: "_intro": b1c56a40 - "Overview": 48a88d56 + "Overview": 4b68a7b5 + "Install Comfy Cloud MCP": b6975c91 "What your agent can do": 2c2a22e6 "MCP tools": a9211dee "Credits and spending": 20e94ef0 - "Install": 445ca642 "Outputs and downloads": a2c8c12f "Related resources": 58e75560 "Feedback": 6872768e "Known limitations": 52477743 - "FAQ": 7b3bdcef + "FAQ": 4e76854d --- import CloudFeature from '/snippets/zh/cloud-feature.mdx' @@ -32,19 +32,308 @@ import CloudFeature from '/snippets/zh/cloud-feature.mdx' 服务器远程运行在 `cloud.comfy.org/mcp`。工作流在 Comfy Cloud GPU 上执行，因此你无需本地 GPU。你的代理通过 HTTPS 与服务器通信；服务器将工具调用转换为经过身份验证的请求，代表你发送给 Comfy Cloud。 -目前支持范围限于 **Claude Code** 和 **Claude Desktop**，它们通过 **OAuth** 登录（一次性的浏览器登录）。更多客户端支持即将推出。 +任何 **MCP 兼容客户端**都可以连接到相同的服务器 URL。**Claude Code**、**Claude Desktop**、**Cursor** 和 **Codex** 在下方有优先设置指导。**Windsurf**、**Amp** 和其他代理使用相同的 URL，搭配 OAuth 或 API 密钥。 -## 你的代理能做什么 + -你无需自己调用 MCP 工具。你的代理会根据你的请求自动选择合适的工具。斜杠命令和提示词（见下文）是将代理导向常用使用例的快捷键，但自然语言同样有效（例如“生成一张猫宇航员的图像”、“放大这张照片”、“找一个 Wan万相 2.2 视频模板”）。 +## 安装 Comfy Cloud MCP + + + 你需要有一个 [Comfy Cloud](https://cloud.comfy.org) 账户才能连接。如果你还没有，请[注册](https://cloud.comfy.org)。设置期间的 OAuth 登录会使用你的 Comfy 账户。 + + +Comfy Cloud MCP 运行于： + +``` +https://cloud.comfy.org/mcp +``` + +选择你的客户端： + + + + 安装 **comfy-cloud** 插件。它将 MCP 连接和斜杠指令集成为一步操作。该插件通过 [Comfy Skills](https://github.com/Comfy-Org/comfy-skills/) 仓库发布，该仓库托管了 Claude Code 插件以及适用于 Comfy 的社区代理技能。 + + + + 添加 Comfy Skills 插件市场（只需一次）： + + ``` + /plugin marketplace add Comfy-Org/comfy-skills + ``` + + + ``` + /plugin install comfy-cloud@comfy-skills + ``` + + + 运行 `/mcp`，选择 **comfy-cloud** → **Authenticate**。你的浏览器会打开并登录，令牌会自动刷新。 + + + + 该插件添加了以下斜杠指令： + + | 指令 | 作用 | + | --- | --- | + | `/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 做什么 | + + + 直接添加服务器： + + ```bash + 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____` 前缀使用你传递给 `claude mcp add` 的名称）。推荐使用上面的插件，因为它将这些封装为更友好的 `/comfy-cloud:*` 指令。 + + + + + Claude Desktop 通过其 UI 将 Comfy Cloud 添加为**自定义连接器**，然后运行 OAuth 登录。 + + + + + + 在侧边栏中，点击 **Customize**（标记为 **1**）。 + + ![Claude Desktop — 打开自定义](/images/agent_tools/claude_desktop_mcp_setup_step1.png) + + + 点击 **Connectors**（标记为 **2**）。 + + ![Claude Desktop — 打开连接器](/images/agent_tools/claude_desktop_mcp_setup_step2.png) + + + 1. 点击连接器标题中的 **+** 按钮（标记为 **3**）。 + 2. 选择 **Add custom connector**（标记为 **4**）。 + + ![Claude Desktop — 添加自定义连接器](/images/agent_tools/claude_desktop_mcp_setup_step3.png) + + + 1. 在 **Name** 字段中输入一个名称，例如 **Comfy Cloud MCP**（标记为 **5**）。 + 2. 将 **Remote MCP server URL** 设置为 `https://cloud.comfy.org/mcp`（标记为 **6**）。 + 3. 点击 **Add**（标记为 **7**）。 + + ![Claude Desktop — 连接器详情](/images/agent_tools/claude_desktop_mcp_setup_step4.png) + + + 1. 当浏览器打开时，选择你的工作区（例如**个人工作区**）。 + 2. 点击**继续**以授权连接器。你已连接。 + + ![Comfy Cloud MCP 授权](/images/agent_tools/auth.png) + + + + Claude Desktop 不支持 Claude Code 斜杠指令。相反，打开**提示词选择器**以使用相同的工作流： + + | 提示词 | 描述 | + | --- | --- | + | `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 工具的工作方式相同。 + + + + Cursor 通过 HTTP 连接到远程 MCP 服务器。在 **Cursor Settings → Tools & MCP** 中添加 Comfy Cloud，或直接编辑你的 MCP 配置文件。 + + + + 在项目中创建或编辑 `.cursor/mcp.json`，或使用 `~/.cursor/mcp.json` 进行全局设置： + + ```json + { + "mcpServers": { + "comfy-cloud": { + "url": "https://cloud.comfy.org/mcp" + } + } + } + ``` + + + 打开 **Cursor Settings → Tools & MCP**。选择 **comfy-cloud** 并点击 **Connect** 通过浏览器登录（OAuth）。令牌会自动刷新。 + + + 用自然语言提问（"生成一张猫宇航员的图像"、"找一个 Wan 2.2 视频模板"）。Cursor 会代表你调用 MCP 工具。 + + + + + 当没有浏览器可用时，在 `X-API-Key` 标头中传递 Comfy Cloud API 密钥。在 [platform.comfy.org/profile/api-keys](https://platform.comfy.org/profile/api-keys) 创建一个（以 `comfyui-` 开头）： + + ```json + { + "mcpServers": { + "comfy-cloud": { + "url": "https://cloud.comfy.org/mcp", + "headers": { + "X-API-Key": "${env:COMFY_API_KEY}" + } + } + } + } + ``` + + 在你的 shell 或系统环境中设置 `COMFY_API_KEY`。不要将密钥提交到版本控制。 + + + + + [Codex](https://developers.openai.com/codex/cli) 通过 Streamable HTTP 连接到 Comfy Cloud。在设置中添加服务器，然后使用 OAuth 登录。 + + + + + + 1. 在 *Logged in with API key* 下点击 **Settings**（标记为 **1**）。 + 2. 点击 **Settings**（标记为 **2**）打开完整设置面板。 + + ![Codex 设置面板 — 步骤 1](/images/agent_tools/codex_mcp_setup_step1.png) + + + 1. 在设置列表中点击 **MCP servers**（标记为 **3**）。 + 2. 点击 **+ Add server**（标记为 **4**）添加新的 MCP 服务器。 + + ![Codex MCP 服务器 — 步骤 2](/images/agent_tools/codex_mcp_setup_step2.png) + + + 1. 选择 **Streamable HTTP** 作为连接类型。 + 2. 在 **Name** 字段中输入一个名称，例如 **Comfy Cloud MCP**（标记为 **5**）。 + 3. 在 **URL** 字段中输入 URL `https://cloud.comfy.org/mcp`（标记为 **6**）。 + 4. 点击 **Save**（标记为 **7**）。 + + ![Codex 添加 MCP 服务器 — 步骤 3](/images/agent_tools/codex_mcp_setup_step3.png) + + + 1. 点击已保存服务器条目上的 **Authenticate**（标记为 **8**）。 + + ![Codex 认证 MCP 服务器 — 步骤 4](/images/agent_tools/codex_mcp_setup_step4.png) + + 2. 在浏览器弹窗中，选择你的工作区并点击**继续**完成登录。你已连接。 + + ![Comfy Cloud MCP 授权](/images/agent_tools/auth.png) + + + + 用自然语言提问（"生成一张猫宇航员的图像"、"找一个 Wan 2.2 视频模板"）。Codex 会代表你调用 MCP 工具。 + + + 从终端注册并登录： + + ```bash + codex mcp add comfy-cloud --url https://cloud.comfy.org/mcp + codex mcp login comfy-cloud + ``` + + 这会将条目写入 `~/.codex/config.toml`（或受信任项目中的 `.codex/config.toml`）。 + + + + 当没有浏览器可用时，添加带有从环境变量读取的标头的服务器。在 [platform.comfy.org/profile/api-keys](https://platform.comfy.org/profile/api-keys) 创建一个密钥（以 `comfyui-` 开头），然后添加到 `~/.codex/config.toml`： + + ```toml + [mcp_servers.comfy-cloud] + url = "https://cloud.comfy.org/mcp" + env_http_headers = { "X-API-Key" = "COMFY_API_KEY" } + ``` + + 在你的 shell 或系统环境中设置 `COMFY_API_KEY`。不要将密钥提交到版本控制。 + + + + + 任何支持**远程 HTTP** 传输的 MCP 客户端都可以连接到 Comfy Cloud。服务器 URL 始终是 `https://cloud.comfy.org/mcp`。 + + + + 添加一个指向 `https://cloud.comfy.org/mcp` 的远程 MCP 条目。大多数客户端使用带有 `url` 字段的 JSON 配置： + + ```json + { + "mcpServers": { + "comfy-cloud": { + "url": "https://cloud.comfy.org/mcp" + } + } + } + ``` + + **Windsurf** 使用 `serverUrl` 代替 `url`。**Amp** 在 **Settings → MCP Servers** 或 `~/.config/amp/settings.json` 中使用相同的 `mcpServers` 结构。 + + + 如果你的客户端支持 MCP OAuth，在提示时通过浏览器登录。否则，添加 API 密钥标头（见下文）。 + + + 重新启动你的客户端。你应该会看到 Comfy Cloud 工具（`search_templates`、`submit_workflow`、`get_output` 等）在 **comfy-cloud** 服务器下注册。 + + + + **无界面 / CI (API 密钥)：** 当 OAuth 不可用时，在 [platform.comfy.org/profile/api-keys](https://platform.comfy.org/profile/api-keys) 创建一个密钥，并将其作为 `X-API-Key` 标头传递： + + ```json + { + "mcpServers": { + "comfy-cloud": { + "url": "https://cloud.comfy.org/mcp", + "headers": { + "X-API-Key": "comfyui-…" + } + } + } + } + ``` + + 对于 Claude Code 终端： + + ```bash + claude mcp add --transport http comfy-cloud https://cloud.comfy.org/mcp -H "X-API-Key: comfyui-…" + ``` + + 推荐使用 `${env:COMFY_API_KEY}` 或你的客户端的密钥插值，而不是在你提交到 git 的配置文件中硬编码密钥。 + + + +## 您的代理能做什么 + +您无需自行调用 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` 会返回一条下载指令，你的代理会在你的 Shell 中执行）。 +1. **发现**可用资源（使用 `search_templates`、`search_models`、`search_nodes`，或对画面风格的问题使用 `cql`）。 +2. **运行**生成任务：如果找到匹配的预构建模板则使用 `run_template`，自定义工作流则使用 `submit_workflow`（需要输入图像时配合 `upload_file`），或使用 `partner_generate` 调用 Flux、Grok、Gemini、OpenAI、Ideogram、Seedance 等合作伙伴模型。 +3. **等待并获取输出**（`wait_for_job`，然后 `get_output` 返回一条下载指令，由您的代理在 shell 中运行）。 -服务器会优先匹配[预构建模板](https://comfy.org/workflows)，然后才从头构建工作流，这样通常能更快得到更好的结果。 +服务器倾向于优先匹配 [预构建模板](https://comfy.org/workflows)，而不是从头构建工作流，这样往往能更快地获得更好的结果。 ## MCP 工具 @@ -121,144 +410,15 @@ import CloudFeature from '/snippets/zh/cloud-feature.mdx' | `submit_feedback` | 获取测试版反馈调查问卷链接 | | `report_session_summary` | 与 Comfy 团队分享匿名化的会话摘要——**仅在你明确同意的情况下**；代理必须先征求你的同意，且摘要中不包含任何提示词、文件路径或个人信息 | -## 积分与消费 - -探索是免费的：`search_templates`、`search_models` 和 `search_nodes` 只需一个 [Comfy 账户](https://cloud.comfy.org)即可使用。运行生成会消耗 Comfy Cloud 积分，需要订阅或积分余额。 - -会产生实际花费的工具受**消费确认**保护。当一次生成使用付费合作伙伴模型（`partner_generate`），或使用包含付费 API 节点的工作流/模板（`run_template`、`run_saved_workflow`、`submit_batch`）时，服务器会阻止执行，直到你的代理确认你同意消耗积分——因此在这些运行之前，代理会先与你确认。免费、仅使用本地节点的工作流不会触发确认。 - -你可以随时向代理询问余额（“我还有多少积分？”）——它会通过 `get_billing_status` 来回答。 - -## 安装 - -选择你的客户端： - - - - 安装插件。连接和指令一步完成。 - - - 在应用中添加自定义连接器，然后登录。 - - - -### Claude Code - -安装 **comfy-cloud** 插件。它一步添加 MCP 连接和斜杠指令。该插件通过 [Comfy Skills](https://github.com/Comfy-Org/comfy-skills/) 仓库发布，该仓库托管 Claude Code 插件和 Comfy 的社区代理技能。 + - - - 注册 Comfy Skills 市场（一次性）： - - ``` - /plugin marketplace add Comfy-Org/comfy-skills - ``` - - - ``` - /plugin install comfy-cloud@comfy-skills - ``` - - - 运行 `/mcp`，选择 **comfy-cloud** → **认证**。浏览器将打开让你登录，令牌会自动刷新。 - - - -该插件添加以下斜杠指令： - -| 指令 | 功能 | -| --- | --- | -| `/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 做什么 | - - - 直接添加服务器： - - ```bash - claude mcp add --transport http comfy-cloud https://cloud.comfy.org/mcp - ``` - - 然后运行 `/mcp`，选择 **comfy-cloud** → **认证**。添加 `-s user` 使其在你所有项目中可用。 - - 此路径仍然暴露与 MCP 提示相同的工作流：`/mcp__comfy-cloud__generate-image`、`/mcp__comfy-cloud__search-models` 等（`/mcp__<名称>__` 前缀使用你传递给 `claude mcp add` 的名称）。推荐使用上面的插件，因为它将这些包装为更友好的 `/comfy-cloud:*` 指令。 - - -### Claude Desktop - -Claude Desktop 通过其 UI 将 Comfy Cloud 添加为自定义连接器，然后运行 OAuth 登录。 - - - - - - 在 Claude Desktop 中，打开 **自定义**，然后选择 **连接器**。 - - ![Claude Desktop 连接器](/images/cloud/mcp/desktop-connectors.png) - - - 点击 **+** 按钮，然后选择 **添加自定义连接器**。 - - ![添加自定义连接器](/images/cloud/mcp/desktop-add-custom-connector.png) - - - 将其命名为任意名称（例如 *Comfy Cloud*），并将 **远程 MCP 服务器 URL** 设置为： - - ``` - https://cloud.comfy.org/mcp - ``` - - ![连接器详情](/images/cloud/mcp/desktop-connector-url.png) - - - 点击 **添加**，然后按提示通过 Claude Desktop 登录。你即连接成功。 +## 积分与消费 - ![通过 Claude Desktop 登录](/images/cloud/mcp/desktop-signin.png) - - +探索功能免费：`search_templates`、`search_models` 和 `search_nodes` 只需一个 [Comfy 账户](https://cloud.comfy.org) 即可使用。运行生成会消耗 Comfy Cloud 积分，且需要订阅或积分余额。 -Claude Desktop 不支持 Claude Code 斜杠指令。取而代之，打开 **提示选择器** 以使用相同的工作流： +实际花费金钱的工具是**消费门槛限定**的。当生成使用付费合作伙伴模型（`partner_generate`）或包含付费 API 节点的工作流/模板（`run_template`、`run_saved_workflow`、`submit_batch`）时，服务器会阻止执行，直到你的智能体确认你同意花费积分——因此，在这些运行之前，智能体会先与你确认。免费的本地工作流永远不会提示。 -| 提示 | 描述 | -| --- | --- | -| `generate-image` | 从文本描述生成图像 | -| `generate-video` | 从文本或图像生成视频 | -| `generate-audio` | 生成音频、音乐或音效 | -| `generate-3d` | 从文本或图像生成 3D 模型 | -| `upscale-image` | 将图像放大到更高分辨率 | -| `remove-background` | 移除图像背景 | -| `search-templates` | 查找预构建的工作流模板 | -| `search-models` | 搜索模型（检查点、LoRA、VAE 等） | -| `search-nodes` | 搜索节点并获取接线建议 | -| `help` | 查看你可以用 ComfyUI Cloud 做什么 | - -你还可以跳过提示，直接用自然语言提问。MCP 工具的工作方式相同。 - -### 无头 / CI（API 密钥） - -Claude Code 和 Claude Desktop 使用 OAuth，因此你不需要 API 密钥。对于**无头或 CI** 环境（无法使用浏览器）的情况，请改用 API 密钥进行身份验证： - - - - 前往 [platform.comfy.org/profile/api-keys](https://platform.comfy.org/profile/api-keys)，点击 **新建 API 密钥** 并复制它（它以 `comfyui-` 开头）。 - - - ```bash - claude mcp add --transport http comfy-cloud https://cloud.comfy.org/mcp -H "X-API-Key: comfyui-…" - ``` - - +你可以随时向智能体询问你的余额（“我还有多少积分？”）——它会通过 `get_billing_status` 回答。 ## 输出与下载 @@ -297,7 +457,7 @@ Comfy Cloud MCP 为早期版本。以下为已知的限制，团队正在努力 **工作流** - **编辑器格式到可执行格式的转换尚不完善。** 已保存的工作流可以通过 `run_saved_workflow` 按文件名运行（服务器会自动转换），但某些节点配置的转换仍不够完美。 -- **通过 `submit_workflow` 生成的资源可能未嵌入工作流元数据。** 在 ComfyUI 中打开时，可能无法恢复其原始工作流。 +- **通过 `submit_workflow` 生成的资产可能未嵌入工作流元数据。** 在 ComfyUI 中打开时，可能无法重新打开其原始工作流。 - **工作流构建依赖于智能体的准确性。** 复杂的多节点工作流可能需要重试或优化。 **文件处理** @@ -313,13 +473,13 @@ Comfy Cloud MCP 为早期版本。以下为已知的限制，团队正在努力 - 目前支持 Claude Code 和 Claude Desktop，两者均通过 OAuth 登录。未来将支持更多客户端。 + 任何支持远程 HTTP 传输的 MCP 兼容客户端都可以连接到 `https://cloud.comfy.org/mcp`。我们为 **Claude Code**、**Claude Desktop**、**Cursor** 和 **Codex** 提供了最优先的配置说明。**Windsurf**、**Amp**、**OpenClaw** 和其他代理使用相同的 URL，通过 OAuth 或 API 密钥连接。参见[安装 Comfy Cloud MCP](#install-comfy-cloud-mcp)。 - Claude Code 和 Claude Desktop 不需要，它们使用 OAuth。仅在没有浏览器的无头或 CI 环境中才需要 API 密钥。 + 对于支持 OAuth 的交互式客户端（Claude Code、Claude Desktop、Cursor、Codex 等）不需要。仅在没有浏览器的无头或 CI 环境中才需要 API 密钥。请参见[安装 Comfy Cloud MCP](#install-comfy-cloud-mcp) 下的 **其他客户端** 标签。 - 付费生成受消费确认保护：当一次运行会消耗 Comfy Cloud 积分时（使用合作伙伴模型，或包含付费 API 节点的工作流/模板），服务器会要求你明确同意后才执行。请参阅[积分与消费](#积分与消费)。 + 付费生成受消费确认保护：当一次运行会消耗 Comfy Cloud 积分时（使用合作伙伴模型，或包含付费 API 节点的工作流/模板），服务器会要求你明确同意后才执行。请参阅[积分与消费](#credits-and-spending)。 不能。斜杠指令是 Claude Code 插件的一部分。Claude Desktop 可以连接到同一个 MCP 服务器（如果你用自然语言提问或使用提示选择器，这些工具也能正常工作），但它不支持 Claude Code 插件或斜杠指令。