Runapi Mcp Server

RunAPI MCP サーバー

画像生成、動画生成、音楽作成、テキスト読み上げ、プロンプト検索、モデル探索 — 4 つのモダリティにわたる 160 以上の実行可能なモデルを 1 つの MCP サーバーで利用できます。

_{Claude Code、Codex、Cursor、Windsurf、VS Code、Roo Code、および MCP 互換ホストで動作します。}

クイックスタート | ツール | 例 | カタログ | プラットフォーム

---

これは何ですか？

RunAPI MCP サーバーは、MCP 互換のコーディングツールを RunAPI に接続します。 アシスタントは RunAPI カタログの閲覧、モデル入力の確認、現在の実行料金の確認、メディアタスクの作成、タスク状況のポーリング、アカウント残高の確認を行えます。

探索ツールは、ビルド時に埋め込まれたカタログを使用するため、API キーなしで動作します。 認証が必要な操作では、login ツール、runapi login、RUNAPI_API_KEY、または共有 RunAPI 設定を使用します。

このパッケージはクライアントのみです。 ローカルの生成バックエンドは実行せず、認証が必要なツールを使う場合のみ RunAPI へのサインインが必要です。

---

ホスト型 MCP

リモート MCP クライアントは、次の場所に直接接続できます。

https://mcp.runapi.ai/mcp

Node.js のインストールは不要です。クライアントがリモート MCP 認証に対応している場合は OAuth を使用するか、RunAPI API キーをベアラー認証情報として設定してください。Cursor、Claude Desktop、VS Code、Windsurf の設定については、ホスト型 MCP の設定ページをご覧ください。

ホスト型 MCP では、以下に記載されている 8 つのビジネスツールを利用できます。ローカルログインは、ローカル MCP パッケージでのみ利用できます。

---

クイックスタート

stdio 経由のローカル MCP を利用するには、Claude Code の MCP コマンドで RunAPI をインストールします。

claude mcp add runapi -s user -- npx -y @runapi.ai/mcp

スコープフラグは、MCP サーバーを保存する場所を指定します。

• -s user：グローバル設定。ユーザーのすべてのプロジェクトで利用できます。
• -s project：チームで共有する設定。現在のリポジトリの .mcp.json に書き込まれるため、コミットできます。

チーム全体で同じサーバー設定を共有するには、プロジェクトスコープを使用します。

claude mcp add runapi -s project -- npx -y @runapi.ai/mcp

Claude Code 以外のプラットフォームや手動での JSON 設定に使える互換性フォールバック：

{
  "mcpServers": {
    "runapi": {
      "command": "npx",
      "args": ["-y", "@runapi.ai/mcp"]
    }
  }
}

ホストで生成済みの設定ファイルが必要な場合は、フォールバックとして従来の init コマンドを使用します。

npx @runapi.ai/mcp init claude
npx @runapi.ai/mcp init cursor
npx @runapi.ai/mcp init vscode
npx @runapi.ai/mcp init windsurf
npx @runapi.ai/mcp init roo

無料のカタログツールは、サインイン前でも利用できます。 タスクの作成、タスク状況の確認、残高の確認には、アシスタントに login ツールを呼び出すよう依頼してください。ブラウザでログイン画面が開き、runapi login が使用するものと同じ ~/.config/runapi/config.json に認証情報が保存されます。 ヘッドレス環境や CI ホストでは、MCP ホストを起動する前に RUNAPI_API_KEY を設定して使用することもできます。

---

ツール

ツール	認証	用途
list_models	なし	埋め込みカタログから RunAPI モデルを一覧表示します。modality、service、action によるフィルターに対応しています。
get_model_info	なし	モデルのスラッグについて、サービス、アクション、モダリティ、入力制約、および現在の実行時価格を返します。モデルが複数のエンドポイントに存在する場合は、service と action を使用してください。
list_actions	なし	エンドポイントのアクション名をモダリティごとにグループ化して返します。
check_pricing	なし	service、action、model の組み合わせに対する現在の実行時価格を返します。
search_prompts	なし	modality、category、tags、q、model、featured、ページネーションで再利用可能なプロンプト例を検索します。
login	なし	ブラウザーでのログインを開始し、RunAPI の認証情報を共有ローカル設定に保存します。
create_task	あり	呼び出し元が生成した必須の idempotency_key を使用してメディアタスクを作成します。デフォルトでは完了まで待機し、wait: false の場合はすぐに返します。
get_task	あり	既存のメディアタスクのステータスと最新のペイロードを取得します。
check_balance	あり	アカウント残高と支出指標を返します。

カタログ、価格、プロンプト検索のツールは、コーディングツール内でファネル上部のディスカバリーに使用するよう設計されています。 タスクと残高のツールは、認証が必要なワークフロー向けに設計されています。

---

使用例

アシスタントに自然言語で質問してください。 アシスタントは、記憶している名前に頼るのではなく、ツールを使って最新のモデルスラッグと価格を確認してください。

カタログを閲覧する

What RunAPI image models are available?

期待される動作：

1. アシスタントが modality: "image" を指定して list_models を呼び出します。
2. 返されたモデルスラッグ、サービス、アクション、必須フィールドを要約します。
3. check_pricing を呼び出さない限り、古い価格を引用しません。

プロンプト例を検索する

Find image prompt examples for a logo.

期待される動作：

1. アシスタントが modality: "image" と q: "logo" を指定して search_prompts を呼び出します。
2. 返されたタイトル、プロンプトテキスト、モデルスラッグ、カテゴリ、タグを要約します。
3. タスクを作成する前に、選択したプロンプトを get_model_info で確認します。

モデルを確認する

Show me the required parameters for this model slug: <model-slug>

期待される動作：

1. アシスタントが get_model_info を呼び出します。
2. 応答が曖昧な場合は、返された候補から該当するサービスとアクションを選び、service と action を指定して get_model_info を再度呼び出します。
3. 必須フィールド、列挙型の制約、範囲の制約、条件付き入力ルール、対応アクション、利用可能な場合は現在の実行時価格を示します。
4. スラッグが見つからない場合は、list_models で別のスラッグを選ぶよう案内します。

メディアタスクを作成する

Generate a square product image with RunAPI. Pick a suitable image model.

期待される動作：

1. アシスタントが list_models を呼び出し、互換性のある画像モデルを選びます。
2. 選択したサービス、アクション、モデルを指定して get_model_info を呼び出し、パラメーターの説明を確認します。
3. リクエストの費用が高い場合、処理に時間がかかる場合、またはバッチ処理の場合は、確認を求めます。
4. この論理タスク用の不透明な idempotency_key を1つ生成し、create_task を呼び出します。
5. 利用可能な場合は、タスク ID、ステータス、出力 URL、コストの各フィールドを返します。

完了まで待機する

ホスト型 MCP は、wait: true を指定した非同期の create_task 呼び出しを、リクエスト単位の SSE として最大 300 秒間維持します。約 5 秒ごとにポーリングし、約 15 秒ごとに SSE ハートビートを送信します。また、MCP クライアントが progressToken を指定した場合に限り、標準の notifications/progress を送信します。最終的な JSON-RPC 応答は同じストリームで届き、その後ストリームが閉じます。

最終的なツール結果には、task_id、最終的な status、completed: true、および RunAPI の result を含む、一致した structuredContent とテキストコンテンツが含まれます。詳細は examples/create-task-and-wait.arguments.json を参照してください。

待機せずに送信する

Create the task but do not wait for completion.

期待される動作：

1. アシスタントが不透明な idempotency_key を1つ生成し、wait: false を指定して create_task を呼び出します。
2. タスク ID を返します。
3. 後から get_task でステータスを確認できます。

タスク作成を安全に再試行する

create_task では、1～512 文字の不透明な idempotency_key が必要です。論理タスクごとに新しいキーを1つ生成し、そのタスクで使用した正確な service、action、model、params とともに保持してください。

接続が閉じた、またはタイムアウトしたために作成結果が不明な場合は、自動的に別のタスクを作成しないでください。再試行する場合は、同じ入力で同じキーを使用してください。異なる入力でキーを再利用すると、競合が返されます。JSON-RPC リクエスト ID や X-Client-Request-Id からキーを生成しないでください。

Completion Wait が期限に達しても、タスク作成は成功しています。エラーではない結果では、task_id、最新の status、completed: false、wait_deadline_reached: true、next_action: "get_task" を含む、構造化コンテンツとテキストコンテンツが一致します。get_task を続けて使用し、代替のタスクを作成しないでください。

タスク作成後にポーリングが失敗した場合や接続が閉じた場合でも、タスクは処理中の可能性があります。get_task を続けて使用し、代替のタスクを作成しないでください。

送信のみの引数については、examples/create-task.arguments.json を参照してください。

アカウント残高を確認する

Check my RunAPI balance.

想定される動作：

1. アシスタントが check_balance を呼び出します。
2. キーが設定されていない場合、ブラウザーでログインするために login を呼び出すか、ヘッドレスホスト向けに RUNAPI_API_KEY について説明します。

カタログの対象範囲

MCP Embedded Catalog は、RunAPI のコントラクトスナップショットから生成されます。 このサーバーのリリースで実行可能なモデルのみが含まれます。

モダリティ	使用するもの
画像	modality: "image" を指定して list_models を呼び出す
動画	modality: "video" を指定して list_models を呼び出す
音声と音楽	modality: "audio" を指定して list_models を呼び出す
ユーティリティ	modality: "utility" を指定して list_models を呼び出す

カタログの内容はリリースごとに変わる可能性があります。 現在のサービス、アクション、モデルのスラッグを確認するには list_models を、各モデルの現在の制約を確認するには get_model_info を使用してください。

---

料金

MiniMax H3 の料金

RunAPI の料金は、check_pricing ツールと公開料金ページで確認できます。 正確な料金について、README ファイルの例を頼りにしないでください。

便利な手順：

1. list_models を呼び出して、候補となるモデルを見つけます。
2. service、action、model を指定して check_pricing を呼び出します。
3. 返された現在の料金を表示するか、runapi.ai/pricing へのリンクを表示します。

無料のカタログツールはタスクを作成せず、アカウント残高も消費しません。

---

プラットフォームの設定

Claude Code、Cursor、Windsurf、VS Code

次を実行します。

claude mcp add runapi -s user -- npx -y @runapi.ai/mcp

すべてのプロジェクトで使用できるようにグローバルにインストールする場合は、-s user を使用してください。 チームで共有する設定として Claude Code にリポジトリ内の .mcp.json を書き込ませる場合は、-s project を使用してください。

MCP 設定を変更した後は、MCP ホストを再起動するか、再読み込みしてください。

互換性のための代替手段：生成される設定

ホストでプラットフォーム固有の JSON ファイルが必要な場合、または Claude Code の MCP コマンドを使用できない場合に限り、init を使用してください。

Claude Code の代替手段：

npx @runapi.ai/mcp init claude

これにより、現在のディレクトリに .mcp.json が書き込まれます。

Cursor の代替手段：

npx @runapi.ai/mcp init cursor

これにより、.cursor/mcp.json が書き込まれます。 Cursor の設定を開き、MCP サーバーが有効になっていることを確認してください。

VS Code の代替手段：

npx @runapi.ai/mcp init vscode

これにより、.vscode/mcp.json が書き込まれます。 VS Code では、生成される設定の最上位キーに servers を使用し、type: "stdio" を指定します。

Windsurf の代替手段：

npx @runapi.ai/mcp init windsurf

これにより、init コマンドで使用した Windsurf ターゲット向けの生成設定が書き込まれます。

Roo Code

次を実行します。

npx @runapi.ai/mcp init roo

これにより、.roo/mcp.json が書き込まれます。

手動設定

examples/ 内のサンプルファイルを出発点として使用してください。 プラットフォームによってラッパーキーやファイルパスは多少異なりますが、すべて同じコマンドを実行します。

npx -y @runapi.ai/mcp

---

設定

サーバーは次の順序で設定を読み込みます。

1. RUNAPI_API_KEY 環境変数。ヘッドレスホストや CI ホストで便利です
2. ~/.config/runapi/config.json。MCP の login ツールまたは runapi login によって作成されます
3. キーなし。この場合も無料のカタログツールを利用できます

設定ファイルは通常、ログインによって管理されます。事前に設定したヘッドレス環境用の設定では、次のように指定できます。

{
  "apiKey": "your_runapi_key"
}

ローカルテスト用にカスタムベース URL を設定することもできます。

{
  "apiKey": "your_runapi_key",
  "baseUrl": "https://runapi.ai"
}

実際の API キーをコミットしないでください。

---

データ同期

このパッケージには、ビルド時の契約データが含まれています。

• data/contract.json：カタログ、アクション、モデルスラッグ、入力制約

リリース前に RunAPI のソースツリーからデータを更新してください。

npm run sync:data

契約の更新には、新しいパッケージリリースが必要です。料金は RunAPI のランタイム API に問い合わせるため、パッケージのスナップショットは使用しません。

---

開発

npm install
npm run typecheck
npm test
npm pack --dry-run

サーバーをローカルで実行します。

npm run dev

手動での初期化スモークテスト：

printf '%s\n' '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"0.1.0"}},"id":1}' | npx tsx src/index.ts

---

パッケージの内容

npm パッケージには、次のものが含まれます。

• コンパイル済みの dist/ ファイル
• 埋め込み済みの data/ ファイル
• プラットフォームの例
• このリポジトリで生成される場合は、評価シナリオ
• README、変更履歴、ライセンス、パッケージメタデータ

node_modules、.env、ローカル設定ファイル、API キーは含まれません。

---

CLI でも利用可能

RunAPI には、ターミナルでのワークフロー向けに別のコマンドラインクライアントもあります。 MCP ホスト内で RunAPI を利用する場合は、この MCP サーバーを使用してください。 シェルコマンド、スクリプト、CI との統合を直接行う場合は、CLI を使用してください。

---

ライセンス

Apache License, Version 2.0 の下でライセンスされています。