> ## Documentation Index
> Fetch the complete documentation index at: https://dripart-docs-recommend-assets-api.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# ComfyUI MCP 服务器

> 通过模型上下文协议（MCP）将 AI 代理连接到 Comfy Cloud 进行图像生成

<Warning>
  **研究预览版：** ComfyUI MCP 服务器目前处于有限的早期访问阶段。功能、工具和行为可能会随着项目发展而变化。感兴趣？[加入等待列表](https://form.typeform.com/to/hHmvw1UH)。
</Warning>

ComfyUI MCP 服务器通过[模型上下文协议（MCP）](https://modelcontextprotocol.io)将 AI 助手（包括 Claude Desktop、Claude Code 和 Cursor）连接到 [Comfy Cloud](https://cloud.comfy.org)。它使 AI 代理能够在云端 GPU 上生成图像、搜索模型/节点/模板以及运行完整的 ComfyUI 工作流，无需本地 GPU。

## 快速开始

### 1. 获取 API 密钥

<Steps>
  <Step title="访问 https://platform.comfy.org/login 并登录">
    请访问 [https://platform.comfy.org/login](https://platform.comfy.org/login) 并使用对应的账号进行登录

    <img src="https://mintcdn.com/dripart-docs-recommend-assets-api/-j561wD0SOuxl3nM/images/interface/setting/user/user-login-api-key-1.jpg?fit=max&auto=format&n=-j561wD0SOuxl3nM&q=85&s=2384fecb0e63c1b2d697e47aad642eaa" alt="访问平台登录页面" width="2294" height="1430" data-path="images/interface/setting/user/user-login-api-key-1.jpg" />
  </Step>

  <Step title="在 API Keys 点击 `+ New` 创建 API Key">
    在 API Keys 点击 `+ New` 创建 API Key

    <img src="https://mintcdn.com/dripart-docs-recommend-assets-api/-j561wD0SOuxl3nM/images/interface/setting/user/user-login-api-key-2.jpg?fit=max&auto=format&n=-j561wD0SOuxl3nM&q=85&s=c01a0e782b7e9c710e3f3bb665697e33" alt="创建 API Key" width="2298" height="1432" data-path="images/interface/setting/user/user-login-api-key-2.jpg" />
  </Step>

  <Step title="输入 API Key 名称">
    <img src="https://mintcdn.com/dripart-docs-recommend-assets-api/72ldDrvzsIyIIl5f/images/interface/setting/user/user-login-api-key-3.jpg?fit=max&auto=format&n=72ldDrvzsIyIIl5f&q=85&s=9cf0fd06f052db36d574f3669a09d026" alt="输入 API Key 名称" width="2298" height="1432" data-path="images/interface/setting/user/user-login-api-key-3.jpg" />

    1. （必填）输入 API Key 名称，
    2. 点击 `Generate` 创建
  </Step>

  <Step title="保存获取到的 API Key">
    <img src="https://mintcdn.com/dripart-docs-recommend-assets-api/72ldDrvzsIyIIl5f/images/interface/setting/user/user-login-api-key-4.jpg?fit=max&auto=format&n=72ldDrvzsIyIIl5f&q=85&s=0577cc516e5358e1421987cca4ae63c8" alt="获取 API Key" width="2298" height="1432" data-path="images/interface/setting/user/user-login-api-key-4.jpg" />

    <Warning>
      由于 API Key 仅在第一次创建时可见，所以请在创建后立即保存，后续无法查看，请妥善保存，请注意不要公开分享你的 API Key,如果对应的 Key 已经泄露，请及时删除并创建新的 API Key。
    </Warning>
  </Step>
</Steps>

### 2. 连接客户端

ComfyUI MCP 服务器托管在 `https://cloud.comfy.org/mcp`。无需本地安装或 Node.js —— 只需将你的 MCP 客户端指向服务器 URL 并提供 API 密钥即可。

<Tabs>
  <Tab title="Claude Code">
    ```bash theme={null}
    claude mcp add comfyui-cloud \
      --transport http \
      https://cloud.comfy.org/mcp \
      -H "X-API-Key: your-api-key-here"
    ```
  </Tab>

  <Tab title="Claude Desktop">
    将以下内容添加到你的 Claude Desktop 配置文件中：

    | 操作系统    | 配置文件路径                                                            |
    | :------ | :---------------------------------------------------------------- |
    | macOS   | `~/Library/Application Support/Claude/claude_desktop_config.json` |
    | Windows | `%APPDATA%\Claude\claude_desktop_config.json`                     |
    | Linux   | `~/.config/Claude/claude_desktop_config.json`                     |

    ```json theme={null}
    {
      "mcpServers": {
        "comfyui-cloud": {
          "url": "https://cloud.comfy.org/mcp",
          "headers": {
            "X-API-Key": "your-api-key-here"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Cursor">
    将以下内容添加到你的 Cursor MCP 配置中（项目中的 `.cursor/mcp.json` 或全局配置）：

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

    更多详情请参阅 [Cursor 的 MCP 文档](https://docs.cursor.com/context/model-context-protocol)。
  </Tab>
</Tabs>

<Info>
  添加服务器后，请重启你的 MCP 客户端以加载新配置。
</Info>

***

## 可用工具

### 发现

| 工具                 | 描述                                                                    |
| :----------------- | :-------------------------------------------------------------------- |
| `search_templates` | 通过文本、标签、媒体类型或模型搜索 [comfy.org](https://comfy.org/workflows) 上的预构建工作流模板 |
| `search_models`    | 通过文本、类型、基础模型或来源搜索模型目录                                                 |
| `search_nodes`     | 通过文本、类别或输入/输出类型搜索可用节点                                                 |

### 执行

| 工具                    | 描述                                      |
| :-------------------- | :-------------------------------------- |
| `submit_workflow`     | 提交 ComfyUI API 格式的工作流以在 Comfy Cloud 上执行 |
| `upload_file`         | 上传用于工作流的输入图像或文件（例如 LoadImage）           |
| `get_job_status`      | 轮询已提交工作流的执行状态                           |
| `get_output`          | 获取已完成工作流的输出图像、视频或音频                     |
| `use_previous_output` | 将一个工作流的输出作为另一个工作流的输入，实现工作流链接            |
| `cancel_job`          | 取消待处理或正在运行的任务                           |
| `get_queue`           | 检查正在运行和待处理的任务数量                         |

### 已保存的工作流

| 工具                     | 描述                       |
| :--------------------- | :----------------------- |
| `list_saved_workflows` | 浏览你在 Comfy Cloud 上保存的工作流 |
| `get_saved_workflow`   | 查看已保存工作流的节点、输入和配置        |

<Info>
  服务器会在从头构建工作流之前先检查是否有匹配的预构建模板，从而获得更好的结果和更快的生成速度。
</Info>

***

## 工作原理

```
┌──────────────┐    HTTPS/MCP    ┌─────────────────────────────────────────────┐
│  AI 代理     │◄───────────────►│            Comfy Cloud                      │
│  (Claude,    │   X-API-Key     │  cloud.comfy.org/mcp → 在云端 GPU 上       │
│   Cursor)    │                 │                        执行工作流           │
└──────────────┘                 └─────────────────────────────────────────────┘
```

你的 AI 代理直接连接到托管在 `cloud.comfy.org/mcp` 的 MCP 服务器。服务器将 MCP 工具调用转换为 Comfy Cloud GPU 上的工作流执行 —— 无需本地服务器或 GPU。

AI 代理使用发现工具查找模板和节点，然后构建 ComfyUI API 格式的工作流 JSON，提交并返回结果 —— 只需用自然语言描述你想要的内容。

***

## 示例提示

安装完成后，在你的 AI 助手中尝试以下提示：

```
生成一张太空中漂浮的猫宇航员图像，卡通风格
```

```
帮我找一些文本转视频的工作流模板
```

```
搜索 SDXL checkpoint 模型，告诉我有哪些可用的
```

```
生成一幅奇幻风景画，有山脉和日落时分发光的河流
```

```
有哪些可用的图像放大节点？
```

代理会搜索匹配的模板，构建 ComfyUI 工作流，将其提交到 Comfy Cloud，并在对话中直接返回生成的图像。

***

## 输出处理

* **图像**会在对话中内联显示（Claude Code）或在工件侧面板中显示（Claude Desktop）
* **视频和音频**输出会以可下载链接的形式返回
* **动态图像**（GIF、WebP）会被保存但不会内联预览，以保留动画效果
* 内联图像预览会调整为 1024px 以实现高效显示；全分辨率输出始终可通过 `get_output` 工具获取

***

## 已知限制

<Warning>
  这是一个早期版本。以下是已知的限制，正在积极改进中。
</Warning>

**工作流**

* **无法通过 ID 运行已保存的工作流。** 你可以浏览和查看已保存的工作流（`list_saved_workflows`、`get_saved_workflow`），但无法直接执行。已保存的工作流使用 ComfyUI 图形格式，需要转换为 API 格式。AI 代理必须从头重建工作流。
* **生成的资源没有工作流元数据。** 通过 MCP 服务器创建的图像不包含元数据中的工作流 JSON，因此在 ComfyUI 中打开时不会显示工作流。
* **工作流准确性取决于 AI。** 代理从自然语言构建 ComfyUI 工作流。复杂的多节点工作流或不常见的节点配置可能需要多次迭代。

**文件处理**

* **上传大小限制**可能因你的 MCP 客户端而异。
* **图像预览会被调整大小。** 内联预览限制为 1024px（JPEG）。全分辨率文件会保存到磁盘。

**认证**

* **仅支持 API 密钥。** 认证需要通过 `X-API-Key` 头部传递 Comfy Cloud API 密钥。基于浏览器的 OAuth 尚不可用。

**客户端特定**

* **Claude Desktop** —— 生成的图像通过 HTML 显示在工件侧面板中，而非原生图像工件。

***

## 故障排除

### MCP 服务器未显示

重启你的 MCP 客户端（关闭并重新打开 Claude Code、Claude Desktop 或 Cursor）。MCP 服务器在启动时加载。请仔细检查配置中的服务器 URL 是否正确为 `https://cloud.comfy.org/mcp`。

### API 密钥错误

在 [platform.comfy.org/profile/api-keys](https://platform.comfy.org/profile/api-keys) 验证你的 API 密钥是否有效。确保密钥通过 `X-API-Key` 头部传递（而非 Bearer token）。如需要，生成新密钥并更新客户端配置。

### 连接错误

如果 MCP 客户端无法访问服务器，请检查：

1. 你是否有活跃的互联网连接
2. 你的防火墙或代理是否阻止了 `cloud.comfy.org`
3. 你是否有活跃的 [Comfy Cloud 订阅](https://www.comfy.org/cloud/pricing?utm_source=docs\&utm_campaign=cloud-api)