OpenRouter MCP Multimodal Server

OpenRouter MCP Multimodal

マルチモーダルAIエージェント向けMCPサーバーです。
インストールは1回 · 21個のツール · 300以上のOpenRouterモデル · テキスト、ビジョン、音声、動画の分析と生成。

クイックスタート · ツール · 使用例 · セキュリティ · トラブルシューティング · 開発 · リリース · FAQ

これは何ですか？

OpenRouter MCP Multimodalは、本番環境向けのModel Context Protocol (MCP)サーバーです。公式MCP Registryにio.github.stabgan/openrouter-multimodalとして登録されています。AIコーディングエージェント（Cursor、Claude Desktop、VS Code、Windsurf、Clineなど）を、stdio経由でOpenRouterの統合LLM APIに接続します。

テキスト専用のMCPサーバーとは異なり、1回のインストールでマルチモーダル機能をすべて利用できます。

本番環境向けの強化： 入出力パスのサンドボックス化（v4.5.2 以降、analyze_* のローカルファイルも対象）、SSRF ガード、_meta.code を含む構造化エラー、MCP 2025-11-25 の構造化出力とツールアイコン、非同期動画の進捗通知、3929 件の自動テスト（3905 件のユニット／モックテスト + 7 件の回帰テスト + 17 件のライブ統合テスト）。

クイックスタート

1. API キーを取得する（無料枠で利用できます）→ openrouter.ai/keys

2. サーバーを実行する

export OPENROUTER_API_KEY=sk-or-v1-...
npx -y @stabgan/openrouter-mcp-multimodal

3. MCP クライアントに追加する — インストールから JSON ブロックを 1 つコピーして、クライアントの設定に貼り付けます。

以下の手動設定にある mcpServers オブジェクトを使用してください。

開始時にクレジットは不要です。 google/gemma-4-26b-a4b-it:free などの無料モデルは、チャットと画像認識で利用できます。動画／音声の生成には通常、クレジットが必要です。

インストール

MCP サーバーはいくつかのパッケージ形式で配布されています。このサーバーは Node.js/TypeScript で実装されています。以下の表では、各エコシステムの方法を、このサーバーの実行方法に対応付けています。

uvx と npx の違い： MCP エコシステムでは、npx は npm（Node）パッケージを実行し、uvx は PyPI（Python）パッケージを実行します。このサーバーは Node ベースのため、uvx は薄い Python ランチャー を使って npx -y @stabgan/openrouter-mcp-multimodal を実行します。Node のインストールは引き続き必要です。

ワンクリック

Cursor
VS Code
Kiro
Claude Desktop / Windsurf / Cline	JSON による手動設定（以下の方法から選択してください）
Smithery	npx -y @smithery/cli install @stabgan/openrouter-mcp-multimodal --client claude
MCP Registry	公式レジストリページ — npm および OCI パッケージ

プロンプトが表示されたら OPENROUTER_API_KEY を貼り付けてください。ディープリンクではプレースホルダーを使用するため、シークレットが URL に表示されることはありません。

手動設定

export OPENROUTER_API_KEY=sk-or-v1-...
npx -y @stabgan/openrouter-mcp-multimodal

{
  "mcpServers": {
    "openrouter": {
      "command": "npx",
      "args": ["-y", "@stabgan/openrouter-mcp-multimodal"],
      "env": {
        "OPENROUTER_API_KEY": "sk-or-v1-..."
      }
    }
  }
}

export OPENROUTER_API_KEY=sk-or-v1-...
uvx mcp-server-openrouter-multimodal
# pin npm version: OPENROUTER_MCP_NPM_VERSION=5.1.3 uvx mcp-server-openrouter-multimodal

{
  "mcpServers": {
    "openrouter": {
      "command": "uvx",
      "args": ["mcp-server-openrouter-multimodal"],
      "env": {
        "OPENROUTER_API_KEY": "sk-or-v1-..."
      }
    }
  }
}

npm install -g @stabgan/openrouter-mcp-multimodal

{
  "mcpServers": {
    "openrouter": {
      "command": "openrouter-multimodal",
      "env": { "OPENROUTER_API_KEY": "sk-or-v1-..." }
    }
  }
}

git clone https://github.com/stabgan/openrouter-mcp-multimodal.git
cd openrouter-mcp-multimodal
npm ci && npm run build

{
  "mcpServers": {
    "openrouter": {
      "command": "node",
      "args": ["/absolute/path/to/openrouter-mcp-multimodal/dist/index.js"],
      "env": { "OPENROUTER_API_KEY": "sk-or-v1-..." }
    }
  }
}

docker run --rm -i -e OPENROUTER_API_KEY=sk-or-v1-... stabgan/openrouter-mcp-multimodal:latest

{
  "mcpServers": {
    "openrouter": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "OPENROUTER_API_KEY=sk-or-v1-...",
        "stabgan/openrouter-mcp-multimodal:latest"
      ]
    }
  }
}

docker run --rm -i -e OPENROUTER_API_KEY=sk-or-v1-... \
  ghcr.io/stabgan/openrouter-mcp-multimodal:5.1.3

{
  "mcpServers": {
    "openrouter": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "OPENROUTER_API_KEY=sk-or-v1-...",
        "ghcr.io/stabgan/openrouter-mcp-multimodal:5.1.3"
      ]
    }
  }
}

npx -y @smithery/cli install @stabgan/openrouter-mcp-multimodal --client claude
# or: --client cursor | vscode | windsurf | ...

claude mcp add openrouter -- npx -y @stabgan/openrouter-mcp-multimodal
# project scope:
claude mcp add --scope project openrouter -- npx -y @stabgan/openrouter-mcp-multimodal

export OPENROUTER_API_KEY=sk-or-v1-...
npx -y @modelcontextprotocol/inspector npx -y @stabgan/openrouter-mcp-multimodal

{
  "mcpServers": {
    "openrouter": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@stabgan/openrouter-mcp-multimodal"],
      "env": { "OPENROUTER_API_KEY": "sk-or-v1-..." }
    }
  }
}

このサーバーを選ぶ理由

ツール

MCP ツールは 21 個あります。それぞれの説明には、エージェントが適切なツールを選び、エラーから復旧できるよう、使用する場面、適切な例／不適切な例、失敗する場合、連携する対象が記載されています。

すべてのエラーには、閉じた分類体系（13 コード）に基づく _meta.code が含まれます。プログラムで処理する場合は、これらの値で分岐してください。

エラーには、利用可能な場合、エージェント向けの次の手順を示す _meta.suggestions が含まれます。

バイナリツールの結果（v4.7.0+）

ツール（generate_image、generate_image_dedicated、generate_audio、text_to_speech、generate_video、generate_video_from_image、get_video_status）は、画像、音声、または動画のバイトデータを返します。4.7.0 以降、この動作が明確になりました。

インラインのデフォルト上限（種類ごと、または全体で上書きできます）。

以前、同じツール結果で保存ファイル と インラインメディアの両方を利用していた場合は、_meta.save_path からファイルを読み取ってください（または、上限未満のときにインラインメディアを取得するには save_path を省略してください）。

例

チャット（無料モデル）

{
  "tool": "chat_completion",
  "arguments": {
    "model": "google/gemma-4-26b-a4b-it:free",
    "messages": [{ "role": "user", "content": "Summarize MCP in one sentence." }]
  }
}

構造化出力を使ったチャット（JSON Schema）

{
  "tool": "chat_completion",
  "arguments": {
    "model": "openai/gpt-4o",
    "messages": [{ "role": "user", "content": "Extract the name and age from: 'Alice is 30 years old.'" }],
    "response_format": {
      "type": "json_schema",
      "json_schema": {
        "name": "person",
        "schema": {
          "type": "object",
          "properties": {
            "name": { "type": "string" },
            "age": { "type": "integer" }
          },
          "required": ["name", "age"]
        }
      }
    }
  }
}

スキーマなしでよりシンプルな JSON を使うには、"response_format": { "type": "json_object" } を使用してください。不正な形式の JSON を自動修正するには、"response_healing": true を追加してください。

画像を分析する

{
  "tool": "analyze_image",
  "arguments": {
    "image_path": "diagram.png",
    "question": "List every label in this diagram."
  }
}

image／prompt ではなく、image_path と question を使用してください。

モデルを検索する（ビジョン + 無料）

{
  "tool": "search_models",
  "arguments": {
    "query": "gemma",
    "capabilities": { "vision": true },
    "limit": 10,
    "offset": 0
  }
}

動画を生成する（非同期）

{
  "tool": "generate_video",
  "arguments": {
    "model": "google/veo-3.1",
    "prompt": "Ocean waves at sunrise, cinematic drone shot",
    "duration": 4,
    "save_path": "river.mp4"
  }
}

max_wait_ms の経過時点でジョブがまだ実行中の場合、レスポンスは _meta.code: JOB_STILL_RUNNING と video_id を含んで正常に返ります。再開するには get_video_status を呼び出してください。これはエラーではありません。

（上記のように）save_path を設定すると、完了時の結果は保存ファイルへのテキストポインターになります。インライン動画ではありません。バイナリツールの結果を参照してください。

テキストを埋め込む（ベクトル埋め込み）

{
  "tool": "embed_text",
  "arguments": {
    "texts": ["What is MCP?", "Model Context Protocol enables tool use for LLMs."],
    "model": "openai/text-embedding-3-small",
    "dimensions": 1024
  }
}

RAG、セマンティック検索、またはクラスタリング用の埋め込み配列を返します。37 以上のモデルに対応しています。単一の文字列、または最大 2048 件のテキストを含む配列を渡してください。

構造化された判定（System One）

{
  "tool": "decide",
  "arguments": {
    "questions": {
      "is_bug": {
        "type": "noul",
        "instructions": "Is this a bug report or a feature request?",
        "criteria": {
          "true": "Describes broken or incorrect behavior",
          "false": "Requests new functionality"
        }
      }
    },
    "state": {
      "ticket": "The login button does not respond when clicked on Safari."
    }
  }
}

生成テキストの代わりに、較正済みの確率を返します。質問の種類は 3 つです。noul（はい／いいえ）、choice（カテゴリを 1 つ選択）、score（順序尺度の評価基準）。モデル：typesafe/jev-1.13（デフォルト）、upstage/solar-decide、microsoft/decision-1。

その他の例：docs/plans/tool-description-improvement.md

セキュリティ

• 入力パスのサンドボックス化 — analyze_* のローカルパスと参照画像は、OPENROUTER_INPUT_DIR（未設定の場合は OPENROUTER_OUTPUT_DIR、次に cwd）の範囲内にある必要があります
• 出力パスのサンドボックス化 — save_path は OPENROUTER_OUTPUT_DIR の範囲内にある必要があります
• 非同期ジョブの読み取り — get_chat_completion_status は、ディスク上のパスを OPENROUTER_OUTPUT_DIR/openrouter-jobs/ 以下に限定して解決します（4.7.0+）
• SSRF 対策 — URL の取得時にプライベート IP と予約済み IP をブロックします
• 信頼できないコンテンツ — 分析結果には _meta.content_is_untrusted: true のタグが付けられます
• プロトタイプ汚染への対策 — すべての API 出力境界（モデルレコード、埋め込み、判定、再ランク付け結果、ログコンテキスト）で、__proto__、constructor、prototype キーを再帰的に除去してから MCP クライアントに転送します
• シークレットのマスキング — stderr の JSON ロガーは API キーと機密値をマスキングします。stdout は MCP プロトコルのトラフィック専用です

サンドボックスを無効にする場合は、OPENROUTER_ALLOW_UNSAFE_PATHS=1 を設定してください（非推奨）。

脆弱性の報告先：SECURITY.md（非公開で報告してください。エクスプロイトを公開イシューとして投稿しないでください）。

設定

開発

git clone https://github.com/stabgan/openrouter-mcp-multimodal.git
cd openrouter-mcp-multimodal
npm install
cp .env.example .env   # add OPENROUTER_API_KEY
npm run build

テスト

CI／クレジット残高がゼロのアカウント向け無料モデル： 統合テストでは、デフォルトで google/gemma-4-26b-a4b-it:free を使用します（OPENROUTER_INTEGRATION_MODEL で変更できます）。GitHub Actions では、リポジトリシークレット OPENROUTER_API_KEY が必要です。

モックテストは src/__tests__/mock/ にあり、ハンドラー、パスのサンドボックス化、SSRF のブロック、モデルキャッシュのページネーション、ツールの説明、構造化出力をカバーします。コアスイートに加え、396 件のテストケースがあります。

npm run lint
npm run format:check
npm run version:check   # package.json vs src/version.ts, server.json, pyproject.toml

リリース

公開される成果物（npm、PyPI/uvx、Docker、GHCR）はすべて、Git タグ（vX.Y.Z）の同じセマンティックバージョンから配布されます。main へのプッシュではテストが実行されますが、npm や PyPI には公開されません。

通常のフロー： conventional commits を main にマージ → Release Please がリリース PR を作成 → マージ → タグが作成される → CI がすべての配布先に公開します。

手動のフロー： すべてのバージョンファイルを更新 → npm run version:check → npm run ci とスモークテスト → コミット → git tag vX.Y.Z → git push origin vX.Y.Z。

完全なチェックリスト、ファイル一覧、CI シークレット、エージェント向けの手順については、以下をご覧ください。

• docs/RELEASING.md — メンテナー向けリリースガイド
• AGENTS.md — AI エージェント向けクイックリファレンス

トラブルシューティング

構造化エラーには、利用可能な場合、エージェント向けの次の手順を示す _meta.suggestions が含まれます。

FAQ

OpenRouter の有料クレジットは必要ですか？

いいえ。まずは無料で始められます。無料モデルはチャットと画像認識に使用できます。音声／動画の生成には通常クレジットが必要です。一部のモデルでは分析時に 402 が返されることがありますが、サーバーはそれを構造化エラーとして通知します。

どの MCP クライアントに対応していますか？

stdio 経由で MCP に対応するクライアントなら、どれでも使用できます。Cursor、Claude Desktop、VS Code Copilot、Windsurf、Cline、Kiro、カスタムエージェントに対応しています。

OpenRouter を直接呼び出す場合との違いは何ですか？

このサーバーは、MCP ツールのスキーマ、セキュリティサンドボックス、エラー分類、モデルのキャッシュ、進捗通知に対応した非同期動画ポーリング、エージェント向けのツールの説明を追加します。これにより、LLM はカスタムの HTTP 接続処理を記述しなくても、適切な機能を呼び出せます。

パストラバーサルに関するセキュリティアドバイザリはどこにありますか？

4.5.2+ で修正済みです。GHSA-3q7p-736f-x44v、SECURITY.md、docs/solutions/security-issues/ を参照してください。

互換性

あらゆる MCP クライアントで動作します。プロトコル：MCP 2025-11-25（2025-06-18 以前との後方互換性があります）。Node ≥ 22（Docker イメージでは Node 24 を使用します）。

ライセンス

Apache 2.0 — LICENSE を参照してください。

コントリビューション

Issue や PR を歓迎します。大規模な変更の場合は、まず Issue を作成してください。

提出前に、npm run ci を実行してください。Release Please で次のリリースを作成できるよう、Conventional Commits（fix:、feat: など）を使用してください。バージョンをリリースする場合は、docs/RELEASING.md を参照してください。