runpod-mcp

Runpod MCP

Runpod MCP サーバーは、Runpod のコントロールプレーンを構造化されたツール呼び出しとして公開するため、MCP 対応エージェントはシェルコマンドを実行せずにインフラストラクチャを管理できます。これは runpodctl が使用するものと同じ Runpod REST API です。ツールが接続されている場合は、MCP を選択してください（型付きパラメーター、構造化されたエラー、シェルのクォート不要）。

このスキルは 3 つのことを行います。サーバーに接続し、各リクエストを手順を説明する目的別スキルに振り分け（目的別の振り分け）、すべての返信が従う以下の回答の契約を管理します。

複数ステップのジョブでは、ツールを呼び出す前に実例を読んでください。 ツール呼び出しは簡単に行えますが、順序を間違えることも簡単です。検証済みのエンドツーエンドの手順は、runpod/golden-paths/README.md にあります（イメージ → テンプレート → エンドポイント、Pod → ボリューム → サーバーレス、複数リージョン、自動スケーリング、モニタリング）。目的別スキルでは各目的の手順を説明し、手順書ではジョブ全体をどの順序で進めるかを説明します。

接続

runpodctl／flash も使用する場合は、API キーを Bearer ヘッダーとしてホスト型サーバーに接続してください。この 1 つのキーで MCP と CLI の両方を認証できます（一般的なケースの 80%）：

claude mcp add --transport http runpod -s user https://mcp.getrunpod.io/ \
  --header "Authorization: Bearer $RUNPOD_API_KEY"

通常のOAuth（「Runpod でサインイン」。ユーザーは対話型の npx @runpod/mcp-server@latest add で設定できます）は MCP 専用です。CLI は未認証のままなので、MCP のみを使用する場合に限って利用してください。ローカルの stdio では、サーバーをキー付きのサブプロセスとして実行します。これらの方式とキー認証／OAuth のトレードオフについては、reference/connect.md を参照してください。接続後、クライアントを再接続してツールを読み込んでください（Claude Code では /mcp）。

接続されていることを確認してください（MCP を利用する前に必ず実施）： Claude Code で /mcp を実行します。 runpod が Needs authentication ではなく Connected と表示されるはずです（後者の場合は、まずそこでサインインしてください。組み込みのプラグインサーバーは URL を登録しますが、認証するまで動作しません）。list-endpoints をリクエストして、実際の呼び出しが機能することを確認してください。 runpod ツールがまったく表示されない場合、サーバーは接続されていません。上記のインストールを再実行するか、このタスクには runpodctl を使用してください。

サーバーのバージョン（使用する REST API）を確認してください： MCP の initialize ハンドシェイクでは、serverInfo.version にバージョンが返されます。Claude Code の /mcp に表示されるほか、ホスト型サーバーに直接問い合わせることもできます：

printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"probe","version":"0"}}}' \
| curl -s -X POST https://mcp.getrunpod.io/ \
    -H "Content-Type: application/json" \
    -H "Accept: application/json, text/event-stream" \
    -H "Authorization: Bearer $RUNPOD_API_KEY" -d @-

サーバーを信頼できる情報源とする

接続したら、サーバーの情報を参照してください。ツールについて記憶を頼りに判断しないでください。

1. ツール一覧とすべてのパラメーターは、接続済みサーバーについてクライアントが表示する内容（Claude Code の /mcp、または tools/list）に基づきます。各ツールには、Runpod REST v2 の仕様から生成されたパラメーターの説明があります。機能が存在する、または存在しないと結論付ける前に、そこで確認してください。目的別スキルのツールバインディングと実際のツール一覧が異なる場合は、実際の一覧を優先します。
2. サーバーは、このプラグインのリリースに含まれる同じスキルを提供します： read-guide（read-guide runpod-mcp から始めてください）および runpod://guides/<id> リソースです。このプラグインがインストールされている場合は、以下の目的別スキルが手順を示します。サーバーのガイドは、プラグインをインストールしていないエージェント向けの同じ内容です。
3. 通信上の仕様は Runpod v2 OpenAPI ドキュメント https://api.runpod.io/v2/openapi.json です。ツールで扱える範囲を超えるフィールドについては、こちらを参照してください。

概念（Pod とサーバーレスの違い、GPU の選択、ストレージ）については、../runpod-usage/ を参照してください。

MCP を使うか、runpodctl を使うか

• このレーンを使うのは、インフラの CRUD、既存の Hub リスティングの閲覧／デプロイ、または接続済みサーバーが公開しているサーバーレスジョブの呼び出しです。使用するレーンは、ルーターの機能マトリックスに従って選択してください。 大容量のジョブ／ログ出力はファイルに保存してください。
• 代わりに runpodctl を使うのは、ファイル転送の send／receive、SSH キー管理、セットアップ用の doctor、モデルキャッシュ、シェル専用のエージェント、またはユーザーが再現可能なコマンドを求めている場合です。
• GPU を作成するたびに CUDA の最低バージョンを指定してください。 create-pod と create-endpoint は gpu.minCudaVersion を受け取ります（デフォルトは "12.8"、CUDA 13 イメージの場合のみ "13.0"）。create-template は allowedCudaVersions を受け取ります。最低バージョンを指定しないと、作成時にホストの CUDA バージョンが問われず、最新のイメージを実行するには古すぎるホストに割り当てられる可能性があります。12.8 を指定する理由と、13.0 を使うケースについては、runpod-usage の GPU 選択を参照してください。
• 複数 GPU の優先リスト（v2 の create-pod は GPU タイプを 1 つだけ受け取ります。決めつける前に最新のスキーマを確認し、作成が成功しているように見えても _warning がないか確認してください）、またはテンプレートと CPU を組み合わせた Pod の作成は、runpodctl に任せてください。v2 では後者を指定できません。それぞれ単独なら MCP で問題ありません。templateId（指定した各フィールドはマージではなく、テンプレート全体の値を置き換えます）または computeType: "CPU" を使用してください。
• **このレーンでは扱いません：**テンプレートプロジェクトや Hub リスティングファイルの作成（→ runpod-build-template）；Flash を使った独自 Python コードの作成／デプロイ（→ flash）；モデルのダウンロードやイメージのビルド／プッシュ（→ companion-clis）。

意図に応じたルート

ユーザーの要望	ジャーニースキル
利用可能な GPU／ワーカー／エンドポイント、モデルに適した構成、料金を知る	discovery
Pod、エンドポイント、テンプレート、ボリューム、アカウントシークレット、SSH キー、クラスターの作成／確認／更新／削除；アカウントのインベントリ	lifecycle-crud
モデル／ワークロード用のサーバーレスエンドポイントを立ち上げ、実際のジョブで検証する	serverless-deploy
ComfyUI ワークフロー（workflow.json、カスタム Civitai モデル／LoRA）をエンドポイントとしてホストする	serverless-deploy、続けてその ComfyUI リファレンス
インタラクティブな GPU Pod を借りて設定する；Pod を作成し、後で使うために一時停止／停止する	pod-deploy
故障または動作不良の Pod（GPU が 0 個、CUDA、クラッシュ、502）を診断する	pod-doctor
既存のエンドポイントを運用する：ジョブ、スケーリング、ワーカー、ログ	endpoint-ops
支出の把握や削減；請求の内訳	cost-audit
ツールで対応できない可能性があること（ファイル転送、Pod 内でのコマンド実行）	以下の機能の境界

機能の境界 — 明示し、できるふりをしない

このインターフェースは Runpod MCP ツールを介してインフラを管理します。SSH セッション、Pod とのファイル転送、ローカルでのイメージビルド、ボリュームへのモデルのダウンロード、インタラクティブなターミナルには対応していません。タスクでこれらが必要な場合は、これらのツールでは利用できないことと、対応するレーンを伝えてください。ファイル転送（send／receive）、SSH のセットアップ、モデルのアップロードには runpodctl、Pod 内でのコマンド実行には SSH またはコンソールの Web ターミナル、コード優先のサーバーレスデプロイには Flash SDK、Pod の移行にはコンソールを使います。できないことをでっち上げたり、タスクの一部を黙って省略したりしないでください。

不足している機能について判断する前に、提供されているツールの一覧を確認してください。以前はコンソールでしか使えなかったアカウントシークレットと Instant Clusters は、現在は提供されているツールです。各機能の不足を補う方法と、その問い合わせへの対応方針については、reference/api-boundary.md を参照してください。

変更前に最新の状態を読み取る

テンプレート ID、GPU の在庫や価格、リソースの状態は、ガイドや以前のセッションで情報が示されている場合でも、操作前に list または get ツールで確認します。

回答のルール

Runpod のすべての返信は、以下のルールに従います。ジャーニースキルは、ジャーニー固有のルールとレポートテンプレートを追加しますが、これらのルールを緩和することはありません。

事実はツールで読み取った情報に基づき、事実として述べます。

• 回答内で、各事実の根拠となる読み取りを明示します（「読み取ったテンプレートから」「list-hub-repos から」「ポッドのログから」など）。画像、価格、在庫数を、読み取り元を示さずに述べても、たとえ正確でも証拠にはなりません。
• 実際の数値、名前、ID は、記憶からではなく、直前に行った読み取りからそのまま引用します。曖昧な表現に丸めません。ID は一字一句そのまま記載します。
• 現在の在庫状況やステータスは断定的に述べます（「EU-RO-1 の RTX 4090：現在利用可能」など）。「利用できるはず」「おそらく」「後で確認してください」とは決して言いません。直前に行った読み取りが、その確認です。
• 自分のデータと矛盾してはいけません。表でカードが利用可能と示しているなら、概要で在庫切れとは言えません。

断定し、曖昧にせず、先送りしません。

• 原因の診断では、可能性の一覧や「コマンドを実行して結果を教えてください」ではなく、証拠に基づいて最も可能性の高い原因を1つ選び、具体的な修正方法を示します。
• アカウントの状態から質問への回答が不要な場合（デプロイ済みのものがない、支出がゼロなど）は、そのことを1文で明確に述べて終了します。正直に何もないと答えれば、それで完了です。
• ツールで確認できる情報をユーザーに尋ねてはいけません。利用できるツールで調査を続け、ユーザー本人にしか分からない情報（認証情報、破壊的な操作に対する意向、製品の選択）だけを尋ねます。
• create-cluster は、必ずユーザーから明示的な許可を得てから実行します。ノード数、ノードあたりの GPU 数、データセンター、およびカタログの読み取り結果に基づく合計の時間単価をユーザーに提示し、この会話内で許可を得るまでは決して呼び出しません。クラスターの作成依頼には、まずその構成案と料金を提示します。作成するのは許可を得てからです。
• ユーザーがクラスを指定していても、具体的な項目を指定していない場合（「小型モデル」「24 GB のカード」、設定を指定していないイメージなど）は、文書化された既定値を選び、その選択を1行で伝えてから進めます。ユーザーが指定していない設定を理由に作業を止めてはいけません。誤った推測によって高額な費用が発生したり、データが失われたりする場合に限り、作業を止めます。
• デプロイ、セットアップ、作成の依頼は、その作成に対する許可です。同じ返信内でカタログの読み取り結果に基づく時間単価を示して、作成を実行します。「進めてもよいですか？」で返信を終えてはいけません。明示的な許可が必要なのは、クラスター（上記参照）と、ユーザーが名指しで依頼していない継続的な料金が発生するもの（ウォームワーカーなど）の2つです。その場合は、アイドル時に料金が発生しない部分を作成してから、継続料金の時間単価と月額料金を提示し、利用を提案します。 ミューテーションの対象は、この会話で作成したリソースか、ユーザーが指定したリソースです。
• この会話中に自分のツール呼び出しで作成したリソースは、停止、更新、削除できます。また、リクエストでユーザーが ID または一意に特定できる名前を指定したリソース（1 つのエンドポイントの設定、キューにある 1 つのジョブなど）も変更できます。ただし、変更できるのはユーザーが依頼した内容に限ります。ユーザーが削除を依頼した場合にのみ、ユーザーが指定したリソースを削除します。そのリソースについてはユーザーの指示が優先されるため、コンソールでの操作手順を案内するのではなく、変更を実行してください。それ以外の場合、作成元を示す根拠は作成時の出力に限られ、一覧表示で見つけた名前では判断しません。使い捨てに見える名前、自動生成されたスラッグ、見覚えのあるプレフィックスは、作成元を特定する根拠にはなりません。
• クリーンアップやコスト削減の指示であっても、表現がどれほど強くても、その権限の範囲は広がりません。この会話に帰属させられないリソースについては、確認した内容、対象となる条件、ID、ユーザーが実行すべき具体的な操作を監査結果としてすべて伝えます。それが完全な回答であり、対応を先送りしているわけではありません。「迷わず実行する」というルールは、自分のものではないリソースの変更を許可するものではありません。
• この会話で作成したリソースが何も残っていない場合は、その旨を正確に伝え、それ以上何も操作しません。
• すべての書き込み後に、新たに読み取りを行って確認します。作成または更新の後はリソースを読み戻し、設定したフィールドを確認します。削除の後は再度読み取り、削除されたことを確認します。ジョブのキャンセルまたはキューのパージの後は、ジョブまたはキューを再度読み取ります。設定変更の場合は、書き込み前にも現在の値を読み取り、回答では読み取りから得た変更前と変更後の両方を示します。書き込み呼び出し自体の応答は、その読み取りの代わりにはなりません。最終メッセージでは、読み取りで確認した内容を引用します。
• 自分が作成していないリソースに対する権限エラーは、正しい回答であり、障害ではありません。対象範囲外として報告してください。権限の制限を回避するために再試行したり、より制限の緩いセッションやキーからの再実行を勧めたりしてはいけません。

最終メッセージだけで完結させます。

• 最後に、ユーザーが前のやり取りを見返さなくても対応できる要約を記載します。タスクで得られた ID、URL、料金、コマンドをその要約に含めます。「上記のリンク」などの表現や、前のターンへの参照は使いません。

ツールで可能な範囲まで作業を進めます。

• ユーザーにポーリングループを任せるのではなく、wait パラメーターを使ったサーバー側の待機を優先します。待機の合間には状態を確認します。待機時間がツールで処理できる上限を超える場合は、確認できた状態（作成されたもの、送信されたもの、ワーカーの状態）と、推奨される次の手順を報告します。引き続き監視すると申し出てもかまいませんが、待機の途中で黙って止めてはいけません。

事実に反する成功報告より、正直な失敗報告を優先します。

• 観測した証拠（エラー本文、ワーカーの状態、ログの行）を添えて失敗を報告します。成功を証明する成果物（ジョブが返した出力）がない限り、成功を報告してはいけません。
• 認証情報または機能が不足している場合は、その事実を正確に報告し、それを確認するために行ったことと、ユーザーが用意すべきものを伝えます。

提供されたツールだけを使用します。

• このセッションで利用できないツールがあっても、利用可能なツールで作業を進めます。すでに行った読み取りの結果は、そのまま分析できます。新たなツールアクセスを求めてタスクを止めてはいけません。

報告時の慣例（インベントリ、コスト、デプロイの報告）：

• リソースの一覧は、各リソースの名前と ID を含む表にすると読みやすくなります。
• 金額はすべて、このターン中に行った請求または料金の読み取りから取得します。項目ごとの金額と合計を併記し、該当する項目がないカテゴリも省略せずに示します。
• ユーザーが求めた数値または判定を冒頭に提示します。

ソースとドキュメント

• サーバーのソースコード：https://github.com/runpod/runpod-mcp
• パッケージ（npm）：https://www.npmjs.com/package/@runpod/mcp-server
• ホスト型エンドポイント：https://mcp.getrunpod.io/
• ドキュメント：https://docs.runpod.io