> ## 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
> 将任意 AI 智能体连接到 Comfy Cloud GPU 或本机上的 ComfyUI。生成图像、视频、音频和 3D，搜索模型、节点与模板，并运行真实工作流。
**公共测试版。** Comfy MCP 目前处于公共测试版阶段。API、工具和行为可能会在迭代过程中发生变化。请参阅[反馈](#反馈)来报告问题或分享建议。
## 概览
**Comfy MCP** 通过[模型上下文协议](https://modelcontextprotocol.io)将 AI 智能体连接到 ComfyUI。连接后，您可以生成图像、视频、音频和 3D，搜索模型、节点和模板，并与智能体聊天运行真实的 ComfyUI 工作流。
它提供两种连接：**Comfy Cloud** 连接和**本地 ComfyUI** 连接，其中本地连接完全开源。
**对以下任何内容感到困惑？最佳方式是将此页面交给您的智能体并寻求帮助。**
### 我该选哪种连接？
**对于新用户，我们建议从云端连接开始。** 这是最简单的设置。如果您使用 claude.ai、ChatGPT 或 Claude Desktop 聊天应用，云端连接也是更兼容的选择。
**如果您已在本地或自己部署的环境中运行 ComfyUI，或者您主要在编码智能体中工作**，比如 Claude Code、Cursor 或 Codex，请从**本地**连接开始。
**对于 Mac 用户，如果您计划运行开源模型，我们推荐云端连接。** 当前的开放权重模型（如 MiniMax H3、LTX-2.3 等的本地版本）都很大，在 Apple GPU 上无法以可行的速度运行。
同时运行两者是正常的，大多数客户端都可以愉快地托管两个 MCP 服务器。它们登录到同一个 Comfy 账户，但**分开**进行：一次登录并不涵盖另一个。
## Comfy Cloud MCP 连接
托管连接，将你的智能体关联到你的 **Comfy Cloud** 账户。无需安装，工作流在 Comfy Cloud GPU 上运行。要了解更多关于 Comfy Cloud 的信息，请参阅 [Comfy Cloud](/zh/get_started/cloud)。
### 设置云端连接
连接之前，你需要一个 [Comfy Cloud](https://cloud.comfy.org) 账户。如果你还没有账户，请[注册](https://cloud.comfy.org)；新用户可获得 **5 次免费运行**，试试看。设置期间的 OAuth 登录会使用你的 Comfy 账户。
Comfy Cloud MCP 运行地址：
```
https://cloud.comfy.org/mcp
```
选择你的客户端：
Claude Desktop 通过其界面将 Comfy Cloud 添加为 **custom connector**，然后运行 OAuth 登录。
在侧边栏中，点击 **Customize**（标记为 **1**）。
点击 **Connectors**（标记为 **2**）。
1. 点击 Connectors 标题中的 **+** 按钮（标记为 **3**）。
2. 选择 **Add custom connector**（标记为 **4**）。
1. 在 **Name** 字段（标记为 **5**）中输入一个名称，例如 **Comfy Cloud MCP**。
2. 将 **Remote MCP server URL** 设置为 `https://cloud.comfy.org/mcp`（标记为 **6**）。
3. 点击 **Add**（标记为 **7**）。
1. 当浏览器打开时，选择您的工作区（例如 **Personal Workspace**）。
2. 点击 **Continue** 以授权连接器。您已连接。
安装 **comfy-cloud** 插件。它一步完成 MCP 连接和斜杠命令的添加。该插件通过 [Comfy Skills](https://github.com/Comfy-Org/comfy-skills/) 仓库发布，这里面托管了用于 Comfy 的 Claude Code 插件和社区智能体技能。
注册 Comfy Skills marketplace（仅需一次）：
```
/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 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____` 前缀使用您在 `claude mcp add` 中传递的名称）。推荐使用上述插件，因为它将这些包装为更友好的 `/comfy-cloud:*` 命令。
Cursor 通过 HTTP 连接到远程 MCP 服务器。Cursor 目前**不**支持 MCP OAuth。在 MCP 配置中使用 Comfy Cloud API 密钥添加 Comfy Cloud。
点击右上角的 **Settings** 齿轮（标注为 **1**）。
1. 在侧边栏中，点击 **Tools & MCPs**（标注为 **2**）。
2. 点击 **+ New MCP Server**（标注为 **3**）→ **Add a Custom MCP Server**。
编辑 `~/.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}"
}
}
}
}
```
在你的 shell 或系统环境中设置 `COMFY_API_KEY`。推荐使用 `${env:COMFY_API_KEY}` 而不是将密钥硬编码在可能提交到 Git 的文件中。
用自然语言提问（例如「生成一张猫宇航员的图像」、「找一个 Wan 2.2 视频模板」）。Cursor 会代表你调用 MCP 工具。
[Codex](https://developers.openai.com/codex/cli) 通过 Streamable HTTP 连接到 Comfy Cloud。在 Settings 中添加服务器，然后使用 OAuth 登录。
1. 点击 *Logged in with API key* 下的 **Settings**（标记 **1**）。
2. 点击 **Settings**（标记 **2**）打开完整的设置面板。
1. 点击设置列表中的 **MCP servers**（标记 **3**）。
2. 点击 **+ Add server**（标记 **4**）添加新的 MCP 服务器。
1. 选择 **Streamable HTTP** 作为连接类型。
2. 在 **Name** 字段（标记 **5**）中输入名称，例如 **Comfy Cloud MCP**。
3. 在 **URL** 字段（标记 **6**）中输入 URL `https://cloud.comfy.org/mcp`。
4. 点击 **Save**（标记 **7**）。
1. 点击已保存的服务器条目上的 **Authenticate**（标记 **8**）。
2. 在浏览器弹出的窗口中，选择您的工作区并点击 **Continue** 完成登录。您已连接。
用自然语言提问（例如「生成一张猫宇航员的图像」、「找一个 Wan 2.2 视频模板」）。Codex 会代表您调用 MCP 工具。
从终端注册并登录：
```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`）。
当没有可用的浏览器时，通过从环境变量中提取的请求头添加服务器。在 [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" }
```
在 shell 或系统环境中设置 `COMFY_API_KEY`。不要将密钥提交到版本控制。
从 [ClawHub](https://clawhub.ai/comfy-org/skills/comfy) 安装 **Comfy Cloud** 技能。它将 OpenClaw 连接到托管的 MCP 服务器（`cloud.comfy.org/mcp`）。仅适用于云端：无法驱动本地 ComfyUI 安装。
```bash theme={null}
openclaw skills install @comfy-org/comfy
```
技能页面：[clawhub.ai/comfy-org/skills/comfy](https://clawhub.ai/comfy-org/skills/comfy)。
注册 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。打开该链接，登录，然后按照 CLI 提示完成流程（可能会要求您使用 `--code` 参数重新运行）。使用 `openclaw mcp status --verbose` 进行验证。
当设置 `auth: "oauth"` 时，OpenClaw 会忽略该服务器条目中的静态 `headers`。切勿将 OAuth 与硬编码的 API 密钥头组合使用。
用自然语言提问（例如「生成一张猫宇航员的图像」、「找一个 Wan 2.2 视频模板」）。OpenClaw 会代您调用 MCP 工具。
在 [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，优先使用 `Authorization: Bearer` 而非自定义的 `X-API-Key` 请求头。某些 OpenClaw 构建版本会在 streamable-http 传输中丢弃自定义请求头；Bearer 能更可靠地通过代理。将 `COMFY_API_KEY` 放入你的 shell 配置文件或 OpenClaw 环境变量中。不要提交该密钥。
任何支持**远程 HTTP**传输的 MCP 客户端都可以连接到 Comfy Cloud。服务器 URL 始终为 `https://cloud.comfy.org/mcp`。
添加指向 `https://cloud.comfy.org/mcp` 的远程 MCP 条目。大多数客户端使用带有 `url` 字段的 JSON 配置：
```json theme={null}
{
"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 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-…"
```
推荐使用 `${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` 获得一个下载命令，由您的智能体在终端中运行。
服务器通常优先尝试匹配[预构建模板](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、采样器、分辨率） |
**生成**
| 工具 | 描述 |
| ------------------ | ------------------------------------------------------------------------- |
| `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=` URL |
| `import_shared_workflow` | 将一个分享链接或裸分享 ID 解析为工作流 JSON，并可选择将其保存到您的账户 |
**Hub URL 分享 ID：** `comfy.org/workflows/-` hub URL 中末尾连字符分隔的十六进制令牌便是分享 ID。例如，`comfy.org/workflows/topaz-starlight-upscale-1c77e82713b7` 的分享 ID 为 `1c77e82713b7`。请将该令牌作为 `share_id` 传递给 `import_shared_workflow`。`share_url` 参数只接受像 `https://cloud.comfy.org/?share=...` 这样的 `?share=` 查询 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` | 搜索模型（checkpoints、LoRAs、VAEs） |
| `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. 一个直接可执行的 **shell 命令**（在 macOS 和 Linux 上为 `curl`，在 Windows 上为 `curl.exe`）。
您的智能体应在您的 shell 中运行该命令。该命令包含目标路径和文件名。
**原样**运行返回的命令。不要对签名 URL 进行重新编码或编辑。签名存在于查询字符串中，如果修改 URL 则会失效。
如果您的 MCP 客户端无法运行 shell 命令（某些纯 GUI 的设置），请复制该命令并在终端中自行运行。
资源的上传和下载取决于客户端的文件访问权限。如果 Claude Desktop 或其他智能体客户端在处理资源上传或下载时遇到问题，这可能与智能体访问本地文件目录的权限有关。对于 Claude 用户，我们推荐 **Claude Code**（桌面应用或终端），它具有更多功能。类似地，对于其他智能体系列，编码智能体通常比网页聊天版本更好。
### 已知限制
Comfy Cloud MCP 是早期版本。以下是已知限制，正在改进中：
**工作流**
* **通过 `submit_workflow` 生成的资产可能不会嵌入工作流元数据。** 在 ComfyUI 中打开时，可能无法重新打开原始工作流。
* **工作流构建依赖于智能体的准确性。** 复杂的多节点工作流可能需要重试或手动调整。
**文件处理**
* **输出需要额外的 shell 下载步骤。** 请参阅[上传与下载](#上传与下载)。
* **上传大小限制**可能因 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 通信，因此可以运行您的工作流，并检查您实际安装中拥有的节点、自定义节点和模型。
**最快设置方式：交给您的智能体。** 将 `https://docs.comfy.org/agent-tools/mcp#installation` 粘贴到您的 AI 客户端中，并让它为您设置本地连接。
### 要求
* **Python 3.10+**
* 位于您 `PATH` 中的 **[comfy-cli](https://github.com/Comfy-Org/comfy-cli)**（`pip install comfy-cli`）：它是每个工具所包装的引擎
* **一个 ComfyUI 工作区**：如果还没有，请使用 `comfy install` 创建一个（已有检出可通过 `comfy set-default ` 使用）
* **用于执行工具的正在运行的 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 客户端指向它。
**`COMFY_BIN`（可选）。** MCP 客户端会以其自身环境启动服务器，这通常**不**包含您 shell 的 `PATH`。如果 `comfy` 位于虚拟环境或非标准位置，请将 `COMFY_BIN` 设置为其绝对路径（例如 `/path/to/venv/bin/comfy`）。以下每个客户端示例都展示了它应放在哪里；如果 `comfy` 已经在客户端启动服务器时所在的环境中，则可以省略。
***
### 手动配置
所有客户端遵循相同的 MCP stdio 协议：将 `comfy-mcp` 命令作为服务器运行。选择你的客户端：
编辑 `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" }
}
}
}
```
一条命令即可注册服务器：
```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" }
}
}
}
```
将服务器添加到 `~/.cursor/mcp.json`（全局）或 `.cursor/mcp.json`（按项目）：
```json theme={null}
{
"mcpServers": {
"comfy-mcp": {
"command": "comfy-mcp",
"env": { "COMFY_BIN": "/path/to/venv/bin/comfy" }
}
}
}
```
***
### 快速开始
从零到生成图像：
```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
```
```bash theme={null}
comfy launch
```
使用上面对应您客户端的代码片段，然后重新启动 / 重新加载客户端，以便工具显示。
例如：
> 「确认我的本地 ComfyUI 正在运行，然后运行位于 `~/workflows/txt2img.json` 的工作流，并向我显示图像。」
在底层，智能体会调用 `server_info` 来确认 ComfyUI 已启动，调用 `run_workflow` 来执行工作流 JSON，并调用 `fetch_outputs` 来收集结果。
***
### 工具
每个工具都映射到一个 `comfy-cli` 命令，并以 `--where local` 运行。亮点如下：
| 工具 | 用途 |
| ------------------------------------------- | ------------------------------------------------ |
| `server_info()` | 检查本地 ComfyUI 是否正在运行、位置以及工作区。**首先调用。** |
| `run_workflow(workflow_path, wait=True)` | 运行工作流 JSON 文件；`wait=False` 会异步提交并返回 `prompt_id`。 |
| `job_status` / `wait_for_job` / `watch_job` | 轮询、等待或流式传输已提交的任务。 |
| `fetch_outputs(prompt_id, out_dir)` | 将已完成任务的输出复制到 `out_dir` 目录中。 |
| `launch_comfyui` / `stop_comfyui` | 启动或停止本地 ComfyUI。 |
| `search_templates` / `fetch_template` | 查找内置模板并写入其可运行的工作流 JSON 文件。 |
| `search_nodes` / `get_node` / `list_nodes` | 检查**本地实时**安装中的节点类（包含自定义节点）。 |
| `search_models` | 列出磁盘上的模型文件。 |
| `validate_workflow` | 在缓慢运行之前，针对实时的 `object_info` 对工作流进行预检。 |
节点自省和模型搜索会读取你的**实时安装**（包含自定义节点），这是与云端连接相比的本地差异化特点。查看[仓库](https://github.com/Comfy-Org/comfy-mcp)以获取完整工具列表和参考。
***
## 相关资源
| 资源 | 作用 |
| ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| [Comfy Skills](https://github.com/Comfy-Org/comfy-skills/) | Claude Code 插件市场和社区技能库。上面使用的 **comfy-cloud** 插件就托管在此；可浏览或贡献更多用于 Comfy 工作流的技能。 |
| [Comfy Cloud on ClawHub](https://clawhub.ai/comfy-org/skills/comfy) | OpenClaw 技能（`openclaw skills install @comfy-org/comfy`），用于托管的 Comfy Cloud MCP 服务器。 |
| [Comfy CLI](/zh/agent-tools/cli) | 命令行工具，用于本地 ComfyUI 的安装/启动，以及从脚本或 CI 调用托管的合作节点（`comfy generate`，测试版）。作为 MCP 的补充，适用于需要终端或自动化工作流的场景。 |
| [在 Comfy Cloud 上分享工作流](/zh/cloud/share-workflow) | 通过 Comfy Cloud UI 分享工作流（MCP 的 `share_workflow` 工具在智能体会话中也可实现分享）。 |
## 相关：Comfy 应用内智能体
想要**在** Comfy Cloud 内部获得智能体体验（聊天，可以构建和编辑你的画面），而不是通过外部 MCP 客户端吗？
Comfy Cloud 上的私有 Alpha 测试。加入候补名单以请求访问。
## 反馈
Comfy MCP 目前是公开测试版。请试试看，并告诉我们哪些地方好用，哪些地方需要改进：
* **[反馈调查](https://links.comfy.org/cloudmcpbeta)**：反馈 bug、请求功能，或分享常规印象。
* **Discord**：[#comfy-mcp-and-cli](https://discord.gg/xWJn6nhE3R)（位于 Comfy Discord 上），用于问题咨询和讨论。
## 常见问题
### 入门
任何兼容 MCP 的客户端。
**云端连接**需要远程 HTTP 支持。**Claude Code**、**Claude Desktop**、**Cursor**、**Codex** 和 **OpenClaw** 在上文有一流的配置说明；**Windsurf**、**Amp** 及其他客户端则使用相同的 URL，配合 OAuth 或 API 密钥。
**本地连接**需要一个能够将本地 stdio 服务器作为子进程启动的客户端。这排除了基于浏览器的客户端。[claude.ai](https://claude.ai) 和 ChatGPT 仅接受远程连接器。
云端连接运行于 `https://cloud.comfy.org/mcp`。
本地连接没有 URL。你的客户端会直接启动 `comfy-mcp` 指令，并通过 stdio 与其通信。
可以。这就是[本地 Comfy MCP 连接](#本地-comfy-mcp-连接)。它会驱动你自己机器上安装的 ComfyUI，因此你的智能体可以看到你实际拥有的模型、LoRA 和自定义节点，并在你的 GPU 上运行。
可以，如果你在本地运行 ComfyUI，我们也推荐这样做。大多数客户端都能轻松托管两个 MCP 服务器，你的智能体也能将它们区分清楚。每个连接都会运行自己的工作流，并返回自己的结果。
不过，这两个登录是**相互独立**的。在其中一个登录并不会让你自动登录另一个，即使使用的是同一个 Comfy 账户。
问问你的智能体。它会在开始任何繁重任务之前读取你的硬件信息。
在 **Mac** 上，请使用云端连接进行生成：如今的开放权重模型体积过大，无法在 Apple GPU 上以可用速度运行。在**配备独立显卡的 PC** 上，24 GB 或以上的 VRAM 可以处理大多数任务，包括视频；8–24 GB 适合图像生成，但视频生成会较慢，或无法装入显存；低于 8 GB 时，请使用云端。
云端连接目前处于**公开测试版**阶段。在我们迭代期间，API、工具和行为可能会发生变化。本地连接适用于本地 ComfyUI 安装。如需反馈问题，请参阅[反馈](#反馈)。
### 费用与访问
在两种连接方式下，发现功能均免费：搜索模板、模型和节点只需一个 Comfy 账户。
在**云端连接**上，运行生成任务需要有效的 Comfy Cloud 订阅；新用户可获得 5 次免费运行。在**本地连接**上，运行完全免费，因为生成在您自己的硬件上执行，但有一个例外：合作伙伴模型会在合作伙伴的基础设施上执行并消耗积分。
对于支持 OAuth 的交互式客户端则不需要，包括 Claude Code、Claude Desktop、Codex 和 OpenClaw。
**Cursor** 需要在您的 MCP 配置中提供 Comfy Cloud API 密钥；该客户端目前尚不支持 MCP OAuth。无浏览器的无头设置和 CI 设置也需要一个。请参阅 [设置云端连接](#设置云端连接) 下的 **Cursor** 和 **其他客户端** 选项卡。
### 使用
你无需自己调用 MCP 工具：你的智能体会根据你的请求来选择它们。通常，它会**发现**可用的工具（`search_templates`、`search_models`、`search_nodes`），**运行**生成任务，然后**等待并获取**输出。参见[你的智能体可以做什么](#智能体可以做什么)。
在**云端连接**下，服务器绝不会在你的机器上写入任何内容：`get_output` 会返回一个临时签名 URL 和一条立即可运行的下载指令，供你的智能体在你的 shell 中执行。参见[上传与下载](#上传与下载)。
在**本地连接**下，ComfyUI 会写入你工作区的 `output/` 目录，`fetch_outputs(prompt_id, out_dir)` 会将已完成任务的文件复制到你指定的任何位置。
无需撤回任何操作：将第二种连接添加到第一种连接旁边即可。
从**本地转向云端**（你需要云端 GPU 或合作伙伴模型）：请你的智能体帮你登录，然后将 `https://cloud.comfy.org/mcp` 添加到你的客户端。
从**云端转向本地**（你想要自己的模型和自定义节点）：安装 ComfyUI 和本地服务器，然后将你的客户端指向它。你的智能体可以帮你完成其中大部分操作。
直接告诉你的智能体即可。两种连接都已添加后，说出你希望任务在哪里运行，例如"这个在 Comfy Cloud 上运行"或"这个在本地运行"，它就会使用正确的连接。没有需要切换的模式，两次运行之间也无需重新配置任何内容。
如果某个工作流对你的机器来说负担过重，你的智能体会告诉你，并建议改为在 Comfy Cloud 上运行。如果只设置了一种连接，请让它添加另一种连接：参见[设置云端连接](#设置云端连接)或[本地 Comfy MCP 连接](#本地-comfy-mcp-连接)。
在**云端连接**下，无需进行任何操作：它是托管服务，因此你始终使用的是当前版本。
在**本地连接**下，请你的智能体来处理。之后，**重新启动你的客户端**或开启新会话：MCP 服务器在会话启动时加载，因此正在运行的服务器会继续提供旧版本，直到你重新启动（或开启新会话）为止。
### 故障排查
不。斜杠指令随 Claude Code 插件提供。Claude Desktop 连接到同一个 MCP 服务器：如果你用日常语言提问或使用提示选择器，这些工具可以正常工作，但它不支持 Claude Code 插件或斜杠指令。
没有 `/comfy` 或 `/cloud` 指令。根据你的连接方式，指令会出现在以下两个前缀之一：
* **插件（推荐）：** `/comfy-cloud:generate-image`、`/comfy-cloud:generate-video` 等。输入 `/comfy-cloud:` 即可看到所有指令。
* **直接连接（无插件）：** `/mcp__comfy-cloud__generate-image` 等。输入 `/mcp__` 即可看到这些指令。
无论哪种方式，你都可以直接用日常语言提问（“生成一张……的图像”）。MCP 工具由模型调用，不需要斜杠指令。
在 Claude Code 中，运行 `/mcp`，选择 **comfy-cloud**，然后选择 **认证**。在 Claude Desktop 中，从 **自定义 → 连接器** 重新打开连接器并触发登录。