runcomfy-mcp

RunComfy MCP

适用于 RunComfy 平台的 MCP 服务 — Serverless API (ComfyUI)、Model API 和 Trainer API。通过 Claude、Cursor 和 Windsurf 等 AI 助手管理部署、运行托管模型、训练 LoRA 并获取结果。

端点：https://mcp.runcomfy.com/mcp

文档：docs.runcomfy.com/mcp

---

功能介绍

31 个工具，与 RunComfy 文档一一对应，涵盖三款产品及账户余额。

Serverless API (ComfyUI) — 在专用端点上运行自己的工作流

文档：docs.runcomfy.com/serverless

类别	工具
部署管理	list_deployments、get_deployment、create_deployment、update_deployment、delete_deployment
推理	submit_request、get_request_status、get_request_result、cancel_request
高级功能	call_instance_proxy

Model API — 按需使用托管目录中的模型

文档：docs.runcomfy.com/model-apis

类别	工具
目录	list_models、get_model、list_model_categories
推理	run_model、get_model_request_status、get_model_request_result、cancel_model_request

无需管理部署，按请求计费。list_models 可按关键字或能力（category=image-to-video）浏览目录；get_model 会返回一个模型的输入架构，包括属性类型、默认值、枚举值和范围；run_model 则运行该模型。这样，助手无需离开这些工具，也不用猜测参数，就能从“帮我制作一段视频”发起有效请求。

条目还包含 description、按 price_unit 计价的 base_price_usd，以及指向模型页面的 model_url。

model_id 是模型页面 runcomfy.com/models 上显示的标识符，包含斜杠，例如 blackforestlabs/flux-1-kontext/pro/edit。文件输入必须是公开的 HTTPS URL。

Trainer API — 数据集和 AI Toolkit LoRA 训练

文档：docs.runcomfy.com/trainer-apis

类别	工具
数据集	create_dataset、list_datasets、get_dataset_status、delete_dataset
数据集上传	upload_dataset_file_from_url、upload_dataset_text_file、get_dataset_upload_urls
训练任务	submit_training_job、get_training_job_status、get_training_job_result、cancel_training_job、resume_training_job、edit_training_job

典型流程：创建数据集 → 上传媒体文件和对应的 .txt 说明文字 → 轮询直至状态为 READY → 使用 AI Toolkit YAML 配置提交任务 → 轮询状态 → 从结果中获取检查点。

由于服务运行在远程，无法读取本地文件。可使用 upload_dataset_file_from_url 上传服务可通过 HTTP 访问的媒体文件，使用 upload_dataset_text_file 内联编写说明文字；对于本地文件或大于 150 MB 的文件，请使用 get_dataset_upload_urls，然后自行将文件内容 PUT 到签名 URL。

账户

类别	工具
余额	get_balance

一个钱包为三款产品提供资金。get_balance 会报告剩余余额：可通过 balance_usd 查看，也可通过 balance_microdollars（美元的百万分之一）进行精确的阈值检查。余额由 api.runcomfy.net 提供，而非按产品分别镜像，因为只需报告一个余额数值。

在两者之间切换

训练好的 LoRA 无需部署即可运行：将其基础模型的 model_id 传给 run_model，并将 LoRA 作为输入，例如 {"lora": {"path": "my_first_lora_3000.safetensors"}}——可以使用 LoRA 资产中的名称，也可以使用公开 URL，例如通过 get_training_job_result 获取的检查点。若要使用指定硬件的专用端点， 请部署它，然后改用无服务器工具。

---

快速设置

每个客户端都需要使用来自 个人资料页面的 RunComfy API 令牌进行身份验证。提供令牌有两种方式：

• API 令牌请求头——适用于任何 Streamable HTTP 客户端。最简单，也是没有浏览器 OAuth 流程的客户端唯一可用的选项。
• 浏览器 OAuth——配置文件中无需填写令牌。Claude.ai、Cursor 以及注册了回环回调的本地客户端（例如 Claude Code）均支持此方式。

Claude Code

令牌请求头（一条命令，无需其他操作）：

claude mcp add --transport http runcomfy https://mcp.runcomfy.com/mcp --header "Authorization: Bearer YOUR_RUNCOMFY_TOKEN"

或者使用浏览器 OAuth——省略请求头，然后在 Claude Code 中运行 /mcp 并选择 Authenticate：

claude mcp add --transport http runcomfy https://mcp.runcomfy.com/mcp

--transport http 是 Streamable HTTP 传输方式。Claude Code 不接受 streamable-http 作为参数值，也不接受单横线形式的 -transport / -header——这两种写法都会在联系服务之前失败。

使用 claude mcp list 检查，结果应显示 runcomfy: connected。

Claude.ai

在 Settings → Connectors → Add custom connector 中添加 https://mcp.runcomfy.com/mcp，然后选择 Connect。Claude 会发现 RunComfy 的 OAuth 2.1 端点，打开 RunComfy 授权页面，并要求提供 RunComfy 个人资料中显示的 API 令牌之一。令牌由 RunComfy 验证，并加密存储在 MCP 授权许可中；它绝不会返回给 Claude。

Cursor

.cursor/mcp.json：

{
  "mcpServers": {
    "runcomfy": {
      "url": "https://mcp.runcomfy.com/mcp",
      "headers": { "Authorization": "Bearer YOUR_RUNCOMFY_TOKEN" }
    }
  }
}

VS Code（Copilot）

.vscode/mcp.json：

{
  "servers": {
    "runcomfy": {
      "type": "http",
      "url": "https://mcp.runcomfy.com/mcp",
      "headers": { "Authorization": "Bearer YOUR_RUNCOMFY_TOKEN" }
    }
  }
}

Windsurf

Settings → MCP：

{
  "mcpServers": {
    "runcomfy": {
      "serverUrl": "https://mcp.runcomfy.com/mcp",
      "headers": { "Authorization": "Bearer YOUR_RUNCOMFY_TOKEN" }
    }
  }
}

其他客户端

• URL：https://mcp.runcomfy.com/mcp
• 传输方式：Streamable HTTP
• 身份验证：每个请求都携带 Authorization: Bearer <token>，或使用 OAuth 2.1 配合回环重定向 URI 或完全匹配的受支持客户端回调

故障排除

症状	原因
401，并显示 RunComfy rejected this API token	令牌错误、已过期或复制时被截断。请在个人资料中生成新令牌——响应正文会说明如何修复。
401，且没有 error_description	请求未携带 Authorization 请求头。请检查请求头是否作为一个参数加上引号：--header "Authorization: Bearer ..."。
OAuth 期间出现 invalid_client_metadata	客户端注册的回调不在回环地址范围内，也不在精确匹配的客户端允许列表中。请使用受支持的回调或令牌请求头。
OAuth 期间出现 invalid_target	配置的 URL 必须严格为 https://mcp.runcomfy.com/mcp——末尾不能有斜杠。RFC 8707 会将令牌绑定到该精确资源。
出现带有 Retry-After 的 503	RunComfy 的 API 无法连接以验证令牌。请重试。
429	来自同一个 IP 的令牌身份验证请求每分钟超过 600 次。

在 RunComfy 个人资料中重新生成令牌即可撤销访问权限。此操作会使令牌请求头和基于该令牌建立的任何 OAuth 许可失效，因为每个 MCP 请求都会向上游重新验证令牌。

---

架构

MCP Client ──RunComfy API token──┐
                                 │   Cloudflare Worker (/mcp)
MCP Client ──MCP OAuth token─────┤   validates the credential, resolves
                                 │   it to one user's RunComfy token
                                 ▼
                         Cloudflare Container
                         (Python FastMCP app)
                                 │ request-scoped RunComfy credential
                 ┌───────────────┼───────────────┐
                 ▼               ▼               ▼
        api.runcomfy.net  model-api.       trainer-api.
         (Serverless)     runcomfy.net     runcomfy.net
                            (Model)          (Trainer)

一个 RunComfy 令牌即可验证所有三个产品，因此所有工具都采用相同的凭据解析方式。

两种凭据都会在请求到达容器前转换为相同的请求级身份标头。它们通过格式区分：OAuth 访问令牌始终采用 userId:grantId:secret 格式，而 RunComfy API 令牌中绝不包含冒号。

• Cloudflare Worker（src/index.ts）— OAuth 2.1 授权服务和受保护资源边界。凭据缺失、无效、过期或受众错误时，会在 MCP 初始化或工具发现之前拒绝请求。
• 直接 API 令牌（src/index.ts）— 通过 Authorization: Bearer 提供的 RunComfy Profile 令牌会在每次请求时向 api.runcomfy.net 重新验证，按来源 IP 限流，并且绝不会原样转发。
• OAuth 同意（src/oauth-bridge.ts）— 验证现有的 RunComfy Profile 令牌，仅将其存储在加密的 OAuth 授权数据中，并签发单独的、绑定受众的 MCP 访问令牌。动态客户端注册接受环回回调（Claude Code 和其他本地客户端）、精确列入允许列表的托管客户端回调，以及 Cursor 的精确旧版应用回调。Cursor 会同时注册 cursor://anysphere.cursor-mcp/oauth/callback、https://www.cursor.com/agents/mcp/oauth/callback 和 http://localhost:8787/callback；即使当前重定向使用 localhost，也必须接受这三个回调。任意自定义协议和回调变体仍会被拒绝，并且必须使用 S256 PKCE。
• Python 容器（server.py）— FastMCP 应用，包含适用于 Serverless、Model 和 Trainer API 的 31 个工具。它没有共享凭据或运营方凭据；只有在经过身份验证的边缘层提供当前用户的请求级 RunComfy 令牌时才会处理请求，否则会默认拒绝。
• Cloudflare Container 会在收到第一个请求时自动启动，空闲 10 分钟后休眠。

---

项目布局

.github/workflows/deploy.yml  CI: typecheck, test, deploy to Cloudflare
src/index.ts          Cloudflare Worker entrypoint
src/oauth-bridge.ts   OAuth consent and RunComfy token validation
server.py             MCP tool definitions (31 tools)
runcomfy_client.py    RunComfy API clients (serverless, model, trainer)
container_app.py      ASGI middleware (request IDs, token forwarding)
container_entrypoint.py  Uvicorn startup
container_runtime.py  Env validation, structured logging
wrangler.jsonc        Cloudflare Worker + Container config
Dockerfile            Container image
.env.example          Local dev config

---

本地开发

# Python 3.11+
python3.11 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
python -m container_entrypoint

本地端点：

• http://127.0.0.1:8000/healthz
• http://127.0.0.1:8000/mcp

本地 Python 端点有意不设置共享备用凭据。 受保护的工具调用必须经过经过身份验证的 Worker 边界。

---

部署

推送到 main 会通过 .github/workflows/deploy.yml 自动部署： 必须通过类型检查、Worker 测试和容器测试，然后通过 wrangler deploy --containers-rollout immediate 同时部署 Worker 和 Python 容器。拉取请求会运行相同的检查，但不会部署。也可以在 Actions 标签页手动运行此工作流。

需要一个仓库密钥：

密钥	用途
CLOUDFLARE_API_TOKEN	对 wrangler.jsonc 中账户具有 Edit Cloudflare Workers 权限的令牌
CLOUDFLARE_ACCOUNT_ID	可选。account_id 已提交到 wrangler.jsonc；仅在要部署到其他账户时设置此项。

手动部署（需要启用 Containers 的 Cloudflare Workers Paid 计划）：

npm install
npm run check
npm test
npx wrangler deploy --containers-rollout immediate

MCP 端点将在 https://mcp.runcomfy.com/mcp 上线（自定义域名已在 wrangler.jsonc 中配置）。

---

环境变量和绑定

这里有意不设置共享的 RunComfy API 密钥。OAuth 状态保存在 OAUTH_KV 绑定中，每个上游请求都与授权该 OAuth 授权的用户绑定。

Worker 变量（在 wrangler.jsonc 中）

名称	默认值	说明
CONTAINER_INSTANCE_NAME	runcomfy-unified	Durable Object 实例名称
CONTAINER_STARTUP_TIMEOUT_MS	15000	容器启动的最长等待时间
CONTAINER_PORT_READY_TIMEOUT_MS	30000	端口就绪的最长等待时间
MCP_MAX_BODY_BYTES	1048576	请求正文大小上限
OPENAI_APPS_CHALLENGE	当前提交令牌	公开的 OpenAI 域名验证令牌，通过 GET /.well-known/openai-apps-challenge 原样提供；未设置或为空时返回 404。替换任何现有令牌前，请先验证其所有权。
MCP_DIRECT_TOKEN_RATE_LIMITER	600 / 60s	通过 API 令牌验证的 /mcp 请求的每 IP 上限
RUNCOMFY_SERVERLESS_BASE_URL	https://api.runcomfy.net	Serverless API 基础 URL
RUNCOMFY_MODEL_API_BASE_URL	https://model-api.runcomfy.net	Model API 基础 URL
RUNCOMFY_TRAINER_API_BASE_URL	https://trainer-api.runcomfy.net	Trainer API 基础 URL

本地 Python 开发（.env 文件）

名称	必填	说明
RUNCOMFY_SERVERLESS_BASE_URL	否	覆盖 Serverless 基础 URL（默认值：https://api.runcomfy.net）
RUNCOMFY_MODEL_API_BASE_URL	否	覆盖 Model API 基础 URL（默认值：https://model-api.runcomfy.net）
RUNCOMFY_TRAINER_API_BASE_URL	否	覆盖 Trainer API 基础 URL（默认值：https://trainer-api.runcomfy.net）
RUNCOMFY_MCP_MOUNT_PREFIX	否	MCP 挂载路径前缀（默认值：空）