runcomfy-mcp

RunComfy MCP

RunComfy プラットフォーム向けの MCP サーバー — Serverless API (ComfyUI)、Model API、Trainer API。デプロイを管理し、ホスト型モデルを実行し、LoRA をトレーニングして、Claude、Cursor、Windsurf などの AI アシスタントから結果を取得できます。

エンドポイント：https://mcp.runcomfy.com/mcp

ドキュメント：docs.runcomfy.com/mcp

---

できること

RunComfy のドキュメントを 1:1 で反映した 31 個のツールを、3 つの製品とアカウント残高にわたって提供します。

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 を使い、署名付き URL に PUT でバイトデータを直接アップロードしてください。

アカウント

カテゴリー	ツール
残高	get_balance

1 つのウォレットで 3 つの製品すべてを利用できます。get_balance は残高を返します。読み取り用の balance_usd と、しきい値を正確に確認するための balance_microdollars（ドルの 100 万分の 1 単位）を確認できます。報告する残高は 1 つだけのため、製品ごとにミラーされず、api.runcomfy.net から提供されます。

LoRA 間の切り替え

トレーニング済みの LoRA は、デプロイしなくても実行できます。ベースモデルの model_id を run_model に渡し、入力として LoRA を指定します。例：{"lora": {"path": "my_first_lora_3000.safetensors"}} — LoRA Assets にある名前、または get_training_job_result から取得したチェックポイントなどの公開 URL を指定できます。選択したハードウェアを使う専用エンドポイントが必要な場合は、デプロイして Serverless ツールを使用してください。

---

クイックセットアップ

各クライアントは、Profile ページで取得できる RunComfy API トークンを使って認証します。指定方法は 2 通りあります。

• API トークンヘッダー — あらゆる Streamable HTTP クライアントで動作します。最も簡単な方法で、ブラウザーの OAuth フローに対応していないクライアントで使える唯一の方法です。
• ブラウザー OAuth — 設定ファイルにトークンを記載する必要はありません。Claude.ai、Cursor、および Claude Code など、ループバックコールバックを登録するローカルクライアントでサポートされています。

Claude Code

トークンヘッダーを使う場合（コマンド 1 つで完了します）。

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 を値として受け付けません。また、ハイフン 1 つの -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 Profile に表示された 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> を指定するか、ループバックリダイレクト URI または正確なサポート対象クライアントコールバックを使って OAuth 2.1 で認証します

トラブルシューティング

症状	原因
RunComfy rejected this API token を伴う 401	トークンが間違っているか、有効期限切れか、コピー時に欠落しています。Profile で新しいトークンを生成してください。レスポンス本文に修正方法が記載されています。
error_description を伴わない 401	サーバーに Authorization ヘッダーが届いていません。ヘッダーが 1 つの引数として引用符で囲まれていることを確認してください：--header "Authorization: Bearer ..."
OAuth 中の invalid_client_metadata	クライアントが、ループバックおよび正確なクライアント許可リストの範囲外のコールバックを登録しました。サポート対象のコールバックまたはトークンヘッダーを使用してください。
OAuth 中の invalid_target	設定 URL は末尾にスラッシュを付けず、https://mcp.runcomfy.com/mcp と完全に一致させる必要があります。RFC 8707 により、トークンはこのリソースに厳密に紐付けられます。
Retry-After を伴う 503	トークンを検証するための RunComfy API に接続できませんでした。再試行してください。
429	1 つの IP アドレスから、トークン認証済みリクエストが 1 分間に 600 件を超えています。

RunComfy Profile でトークンを再生成すると、アクセスを取り消せます。すべての MCP リクエストでトークンが上流で再検証されるため、トークンヘッダーと、それを使って作成された OAuth グラントは無効になります。

アーキテクチャ

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)

1 つの RunComfy トークンで 3 つすべての製品を認証するため、同じ認証情報の解決処理ですべてのツールを利用できます。

どちらの種類の認証情報も、コンテナに到達する前に、リクエスト単位の同じ ID ヘッダーに統合されます。形式によって区別されます。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 が使用される場合でも、3 つすべてを受け入れる必要があります。任意のカスタムプロトコルやコールバックの別形式は引き続き拒否され、S256 PKCE が必須です。
• Python コンテナ（server.py）— Serverless、Model、Trainer API にまたがる 31 個のツールを備えた FastMCP アプリです。共有の運用者用認証情報は持たず、認証済みのエッジから現在のユーザーのリクエスト単位の 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 タブから手動で実行することもできます。

リポジトリのシークレットが 1 つ必要です。

シークレット	用途
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 のマウントパスのプレフィックス（デフォルト：空）