Claude CodeにRunway Devプラグインを入れて動画生成APIをアプリに組み込む
Runway Dev(インストールIDはrunway-api)はMCPと7つのスキルでRunwayの動画・画像・音声生成APIの組み込みを支援します。導入、認証の分け方、失敗タスクの調べ方まで。
Runway Dev(インストールIDは runway-api)は、Runwayの動画・画像・音声生成APIを自分のアプリに組み込む作業を、コーディングエージェントに任せるためのプラグインです。中身は、Developer Portalのアカウントに接続するMCPサーバーと、SDKの使い方を教える7つのスキルです。
Claude Codeから入れる場合の手順は2コマンドで済みます。注意が要るのは、その後です。MCPのブラウザ認証と、アプリが使うAPIキーは別物で、どちらも人間が済ませる前提になっています。この記事では導入から接続確認、スキルの使い分け、失敗したタスクの調べ方までを順に説明します。
このプラグインがエージェントに渡すもの
Runway Devプラグインが提供するのは、次の2つです。
- Runway Dev MCP: Developer Portalのアカウントに接続します。使えるモデルと価格・制限の参照、コスト・速度・品質に応じたModel Routerの設定(クレジット上限は任意)、リアルタイムアバターの管理ができます。失敗したタスクやルーティングの判断を調べる用途にも使えます。
- スキル: 公式SDKでAPIを組み込む手順と、モデル・Model Router・Recipe・Workflow・リアルタイムアバターごとの作り方を教えます。
動画を生成するのはプラグインではありません。生成を呼び出すコードを、自分のアプリのサーバー側に書かせるための道具です。スキルの側も、実際の生成は実行しない作りになっています。ローカルの型チェックやビルド、SDKをモックしたテストで検証し、本番の呼び出しはユーザーのアプリから動かすよう案内します。
Runwayには、チャット内でメディアを生成する別のMCP(mcp.runwayml.com)もあります。こちらはアプリへの組み込み用とは別物で、組み込みを手伝うのはRunway Dev側です。
Claude Codeへの導入手順
Runway自身が運営するマーケットプレイスから入れます。
claude plugin marketplace add runwayml/skills
claude plugin install runway-api@runway-devマーケットプレイス名は runway-dev、プラグインIDは runway-api です。表示名はRunway Devなので、画面と指定名が違って見えます。リポジトリをクローンして試すときは、パスを渡します。
claude plugin marketplace add /absolute/path/to/skills
claude plugin install runway-api@runway-dev入れたら、Claudeにアカウント接続の手伝いを頼むか、セットアップのスキルを直接呼びます。
/runway-api:runway-dev-setupブラウザのサインインと同意の画面は、自分で操作します。エージェントに自動化させない前提で、スキル側もその手順になっています。
Anthropicが管理する runway-api@claude-plugins-official の掲載もあります。こちらはRunway側のマーケットプレイスと別のバージョンに固定されている場合があります。最新のスキルを使いたいか、掲載に合わせたいかで入手元を決めます。
マーケットプレイスをURLで配る側の注意点は、プラグインマーケットプレイスをURLで配る落とし穴で扱っています。
接続確認はwhoamiとlist_projects
OAuthが終わったら、MCPの whoami でつながっているアカウントを確かめます。Developer Portalのメールアドレスが返れば成功です。アプリに組み込む作業なら、続けて list_projects で対象プロジェクトを選びます。
プロジェクトが複数あるとき、エージェントが勝手に選ぶことはありません。スキルには「プロジェクトIDを推測しない」「複数候補なら選んでもらう」と書かれています。
接続が途中で止まる典型は、HTTP 403の developer_not_found です。OAuthの本人確認は通っているものの、Developer Portal側のセットアップが済んでいない状態を指します。エラーに含まれる signup_url(新規)か login_url(既存アカウント)をユーザーに見せ、ブラウザで完了してから再試行します。古いサーバーは login_url だけを返すことがあります。
Needs authenticationと表示されたら、プラグインで入れた場合は同梱のサーバーを使います。セットアップのスキルは、プラグインがMCP接続を runway-dev というサーバーとして同梱していると説明しています。
プラグイン同梱のMCPを認証する流れ
- 1
/mcp を開く
Claude Codeのセッション内で
/mcpを実行します。 - 2
同梱の runway-dev を選ぶ
別名のサーバーを新しく足さず、一覧にある
runway-devを選びます。 - 3
通常のブラウザで認証する
サインインと同意は自分で済ませます。
- 4
同じセッションで再試行する
MCPツールをそのまま呼び直します。新しいセッションが要るのは、それでも認証済みのツールが出ないときだけです。
MCPだけを単体で足した場合は、サーバー名が変わります。Runwayのドキュメントでは claude mcp add で追加するときの名前を runway-dev-mcp とし、/mcp ではその名前を選びます。端末から認証するなら、Claude Code 2.1.186以降で claude mcp login runway-dev-mcp が使えます。SSH先など、ローカルでブラウザを開けないときは、2.1.191以降の --no-browser で認証URLを表示させます。追加コマンドは、後述のつまずきやすい点にあります。
MCPの認証とAPIキーは別の仕組み
Runway Devでは、認証が2系統に分かれます。ここを混ぜると、どちらも動かなくなります。
| MCP | アプリのSDK | |
|---|---|---|
| 認証 | MCPブラウザのOAuth | アプリのSDKプロジェクトのAPIキー |
| 設定場所 | MCPプラグインが持つMCP接続 | アプリのSDKサーバー側の環境変数 RUNWAYML_API_SECRET |
| 使う人 | MCPエージェント | アプリのSDKあなたのアプリ |
| 禁止事項 | MCP設定にAPIキーを書かない | アプリのSDKブラウザ側コード・チャット・ソース管理に置かない |
Developer PortalでAPIキーを用意する流れ
- 1
プロジェクトを作る
アカウントを作り、プロジェクトを作ります。プロジェクトがアプリ1つ分に相当します。
- 2
キーを作る
API Keysのタブで、名前を付けてキーを作ります。
- 3
キーを控える
キーは一度しか表示されません。パスワードマネージャーなどに控えます。
- 4
クレジットを追加する
billingのタブでクレジットを追加します。
クレジットの最低額は10ドルで、1クレジットは0.01ドルです。キーの作成と無効化にはAdminかDeveloperの役割、クレジットの追加にはAdminかBilling adminの役割が必要です。プロジェクトからメンバーを外してもそのメンバーのAPIキーは失効しないので、キーは別に無効化します。
エージェントには、キーの値をチャットに貼らせないのが決まりです。スキルは RUNWAYML_API_SECRET が設定済みかを、値を出力せずに確認するよう指示しています。
7つのスキルの使い分け
プラグインにはスキルが7つ入っています。依頼の内容に合うものが自動で選ばれますが、何を頼めるかを知っておくと指示が短く済みます。
| スキル | 向く依頼 |
|---|---|
runway-dev-setup | 向く依頼アカウント・プロジェクトの接続、APIキー設定の案内 |
runway-dev | 向く依頼共通の土台。サーバー境界、現行ドキュメントの参照、認証情報、SDK、エラー |
runway-dev-models | 向く依頼モデルのエンドポイントを直接呼ぶ組み込み |
runway-dev-model-routers | 向く依頼保存済みModel Router設定の組み込みと管理 |
runway-dev-characters | 向く依頼リアルタイムのCharactersとSession |
runway-dev-recipes | 向く依頼ドキュメント化されたRecipeのパイプライン |
runway-dev-workflows | 向く依頼公開済みのRunwayアプリのWorkflowをAPIから呼ぶ |
モデルを固定するか、Model Routerに任せるか
特定のモデルを指定するなら runway-dev-models です。モデルの選定が必要なときや、プロジェクトで使える範囲が結果に響くときは、MCPの list_models で現在の対応状況を引きます。モデルの名前から使えるかどうかを推測しないのが、スキルの方針です。
選択を任せたいなら runway-dev-model-routers です。アプリ側は特定のモデルではなく、保存済みのルーティング設定の configId を持ちます。SDKの呼び出しは用途ごとに generate.video、generate.image、generate.audio を使います。
つまずきやすいのは識別子です。Routerのレコードを指すUUIDと、SDKに渡す configId は別の値です。SDKのリクエストに渡すのは configId の方です。
CharactersはPortalでの呼び名
Developer Portalでは「Characters」、APIとSDKでは「Avatars」と呼びます。リアルタイムの1回の会話がSessionです。SessionはSDK(@runwayml/sdk)でサーバー側から作り、ブラウザには接続に必要な一回限りの値だけを渡します。ReactならReact用コンポーネント(@runwayml/avatars-react)、React以外のウェブなら @runwayml/avatars を使います。
RecipeとWorkflow
runway-dev-recipes は、SDKの client.recipes 配下のメソッドを使います。バージョンはガイドが示すものを固定するのが基本で、自動で最新に追随する指定は、ユーザーが望んだときだけです。
runway-dev-workflows は、Runwayのアプリ側で公開済みのWorkflowを呼ぶ用途です。接続情報が必要なときはMCPの get_workflows_setup_guide を使いますが、これはリンクと公開の手順を返すだけです。Workflowの入出力の中身は、Developer Portalかドキュメントのworkflow API(一覧・詳細)で確かめます。公開されていないWorkflowの挙動を推測して書かない、というのがスキルの規則です。
依頼の出し方とCLAUDE.mdに書いておく規約
スキルが現行ドキュメントを自分で引くため、依頼は目的と置き場所だけで足ります。例えば次のような形です。
商品紹介ページに、画像から短い動画を作るボタンを付けたい。
Runway Devのスキルに沿って、サーバー側のAPIルートとローディング・
失敗時の表示までを実装して。実際の生成は実行しないで、
型チェックとSDKをモックしたテストで確かめて。プロジェクト固有の約束はCLAUDE.mdに置いておくと、依頼のたびに書かずに済みます。次のような断片が使えます(スキルの指示を、プロジェクトの規約として書き出した例です)。
## Runway API
- Runwayの呼び出しはサーバー側のルートだけに置く。ブラウザのコードから直接呼ばない
- APIキーは `RUNWAYML_API_SECRET` を既存のシークレット管理で読む。値を出力・コミットしない
- モデルIDやスキーマは記憶で書かない。`list_models` と現行のAPIリファレンスで確かめる
- 実際の生成(課金が発生する呼び出し)はエージェントが実行しない。モックしたテストまで
- 生成結果の署名付きURLは期限付き。後で使う素材は自前のストレージへ保存する最後の1行は、SDKの出力URLの扱いに由来します。署名付きの出力URLとアップロードURLには有効期限があり、長く使うメディアはアプリ側で保存し直す必要があります。
生成タスクが失敗したときの調べ方
Runwayの呼び出しは、タスクを作って完了を待つ形です。SDKは待機用のヘルパー(Node.jsでは waitForTaskOutput()、Pythonでは wait_for_task_output())を、create() の戻りに直接つなぐ書き方が公式の書き方です。自前でポーリングのループを足さず、失敗(TaskFailedError)とタイムアウト(Node.jsは TaskTimedOutError、Pythonは TaskTimeoutError)を例外として扱います。
失敗したときのエージェントの動きは、かなり抑制的です。
失敗タスクに対するエージェントの動き
- 1
失敗メッセージとコードを報告する
タスクIDを
get_taskに渡して取得します。 - 2
定義がなければ、そう伝える
ドキュメントにそのコードの定義がない場合です。
- 3
原因は判断できないと述べて止まる
元の入力やプロバイダーの拒否理由が手元にない場合です。
ルーティングの履歴は「どのモデルが選ばれたか」を説明するもので、後続のタスクの失敗理由ではありません。そのため、原因の候補に順位を付けたり、入力やRouterの変更を勧めたりしない決まりです。自動再送もしません。生成には課金が絡むので、同じ依頼を勝手に再実行しない設計になっています。足りないのは多くの場合、リクエストのログです。個人情報や秘密を除いたリクエスト内容か、アプリのログを渡すと、診断が先に進みます。
つまずきやすい点
別名でMCPを足してしまう
プラグインは、MCP接続を runway-dev というサーバーとして持っています。claude mcp add で別の名前の項目を作ってサインインしても、認証情報は接続ごとに結びつくため、プラグイン側のサーバーは認証されません。認証が必要になったら、/mcp から同梱の runway-dev を使います。ドキュメントにある claude mcp add --transport http --scope user runway-dev-mcp https://dev.runwayml.com/mcp は、プラグインを使わずMCPだけを足す場合の手順で、その場合のサーバー名が runway-dev-mcp です。
プラグイン以外のMCP追加を管理設定が止める環境
組織の管理設定でプラグイン以外のMCP追加が禁止されていると、単体のMCP追加は通りません。症状と見分け方はclaude mcp addが失敗する原因にあります。管理設定の許可範囲によっては、プラグイン経由の導入だけが通ります。
Claudeプラグインではアバターを作れない
Claude向けの接続先は https://dev.runwayml.com/mcp/claude で、create_avatar ツールが含まれません。新しいアバターはDeveloper Portalで作ります。MCPだけをClaude Desktopなどに足す場合の接続先は https://dev.runwayml.com/mcp です。
認証の期限切れ
MCPのOAuthが何度も切れる場合は、MCP OAuthが毎日Connection expiredになる原因と再接続手順を見てください。
スキルだけ、MCPだけの導入
npx skills add runwayml/skills --skill runway-dev --skill runway-dev-models --agent cursor claude-code codex のようなスキル単体の導入では、MCPは自動で設定されません。逆にMCPだけを足してもスキルは入りません。同じスキルを二重に入れないよう、1つのスキルに対して導入経路を1つに決めます。
まとめ
動画や画像の生成をアプリに入れる作業では、モデルの種類、課金、非同期タスク、キーの扱いと、気を配る点が多くなります。Runway Devプラグインは、そのうち「現行のAPIを読む」「キーを正しい場所に置く」「実生成を勝手に回さない」を、スキルの規則として固定するものです。
導入は2コマンドですが、効果を左右するのは接続の分け方です。MCPのOAuthはエージェントのため、APIキーはアプリのため、と覚えておけば、developer_not_found や認証の失敗が出ても切り分けられます。プロジェクトの規約としてCLAUDE.mdに数行を書いておけば、毎回の依頼を短くできます。