openrouter-admin

openrouter-admin-mcp

OpenRouter 管理 API 用の MCP サーバーです。Claude Code、Claude Desktop、Cursor、または MCP 対応クライアントから、クレジット、推論キー、ガードレール、組織メンバー、使用状況分析をプログラムから操作できます。

デフォルトでは読み取り専用です。破壊的な書き込み操作は、オプトインの環境変数フラグで有効にします。

これは推論プロキシではありません。アカウントを管理できますが、補完リクエストは実行できない OpenRouter のプロビジョニング API キーを使用します。

概要

OpenRouter の UI は単発の設定変更には便利ですが、キーごとの支出確認、モデル／日ごとの使用状況の詳細表示、アカウント全体のガードレール設定、上限の変更には多くのクリックが必要です。このサーバーは、それらの操作を MCP ツールとして公開します。Claude に「今週クレジットを使い切ったのは何ですか？」「1 日あたり $0.30 の上限を設定した一時キーを作成して」「新しい本番キーを 1 日あたり $50 のガードレールに関連付けて」と尋ねるだけで、1 回のターンで実行できます。

機能

OpenRouter 管理 API をラップする 26 個のツール：

• or_overview — クレジット、アクティブなキー（リセット／有効期限を含む）、本日 UTC のモデルごとの消費量を一度に表示するダッシュボード。
• limit_reset（日次／週次／月次）と expires_at を含む、推論キーの CRUD。
• ガードレールの CRUD — プロバイダー／モデルの許可リストと ZDR の適用に対応した、アカウント全体の支出上限。キーまたは組織メンバーに一括割り当てできます。
• アクティビティの詳細表示 — by_model、by_day、by_provider、by_key ごとに集計します。各行にはトークンレベルの内訳（プロンプト／補完／推論）が含まれます。
• 生成の検索 — gen-… ID を指定して、個々の推論呼び出し（コスト、トークン数、レイテンシ、終了理由）を取得します。
• モデルとエンドポイントの検出 — 100 万トークンあたりの最新価格、プロバイダーごとの稼働率、ZDR 準拠のエンドポイントを確認できます。

基盤機能：Retry-After に対応した 429／5xx の HTTP リトライ、セッション内の GET キャッシュ、書き込み時のキャッシュ無効化を備えています。生のフィールドを返すため、解釈はエージェントに委ねられます。

インストール

ワンクリック

インストール後、プレースホルダーの sk-or-v1-... を実際のキーに置き換えてください。

手動

npx で実行する（インストール不要）か、グローバルにインストールします。

npx -y openrouter-admin-mcp
# or
npm install -g openrouter-admin-mcp

設定

https://openrouter.ai/settings/provisioning で Provisioning キーを作成し、MCP クライアントの設定にサーバーを追加します。

Claude Code（~/.claude.json）または Claude Desktop（claude_desktop_config.json）：

{
  "mcpServers": {
    "openrouter-admin": {
      "command": "npx",
      "args": ["-y", "openrouter-admin-mcp"],
      "env": {
        "OPENROUTER_PROVISIONING_KEY": "sk-or-v1-..."
      }
    }
  }
}

クライアントを再起動してサーバーを読み込みます。デフォルトでは読み取り専用アクセスが有効になります。キーの作成、変更、削除を有効にするには、以下の書き込みツールを有効にするをご覧ください。

書き込みツールを有効にする

破壊的な操作（or_key_create、or_key_update、or_key_delete）は、プロンプトインジェクションされたツール呼び出しによる意図しないキーの変更を防ぐため、デフォルトで無効になっています。有効にするには、env ブロックに OPENROUTER_ADMIN_ALLOW_WRITE を追加します。

"env": {
  "OPENROUTER_PROVISIONING_KEY": "sk-or-v1-...",
  "OPENROUTER_ADMIN_ALLOW_WRITE": "1"
}

サーバーは、起動したモードをログに記録します。

openrouter-admin-mcp running on stdio (write tools: ENABLED)

読み取りツール（or_overview、or_credits、or_current_key、or_keys_list、or_key_get、or_activity）は、このフラグの値にかかわらず常に利用できます。

ツール

読み取り（常に利用可能）

ツール	目的
or_overview	ダッシュボードの概要を一度に表示します。クレジット、アクティブなキー、今日のモデル別消費量を確認できます。
or_credits	アカウント残高：購入総額、使用総額、残額。
or_current_key	サーバーが使用している Provisioning キーのメタデータ。
or_keys_list	すべての推論キーと、使用状況、上限、リセット間隔、有効期限。
or_key_get	ハッシュで指定したキーの詳細。
or_activity	直近 30 UTC 日間の使用状況。フィルター：date、api_key_hash、user_id。集計：none、by_model、by_day、by_provider、by_key。
or_generation	gen-… ID で指定した推論呼び出しを取得します（コスト、トークン数、レイテンシ、終了理由）。
or_models	モデルカタログ。100 万トークンあたりの価格、コンテキスト長、モダリティを表示します。絞り込み可能です。
or_model_get	1 つのモデル ID の詳細。
or_model_endpoints	モデルのプロバイダー別エンドポイント：価格、稼働時間、ステータス。
or_models_user	アカウントのプライバシー／ガードレール設定に基づいて絞り込んだモデル。
or_zdr_endpoints	プライバシー要件のあるワークフロー向けの ZDR 準拠エンドポイント。
or_guardrails_list	すべてのガードレール：limit_usd、リセット、許可／ブロックリスト、ZDR。
or_guardrail_get	1 つのガードレールの詳細。
or_guardrails_assignments	複合ツール：どのキー／メンバーがどのガードレールに紐付けられているかを表示します。
or_org_members	OpenRouter 組織のメンバー（Management キー＋組織アカウント）。

書き込み（OPENROUTER_ADMIN_ALLOW_WRITE=1 でオプトイン）

ツール	目的
or_key_create	新しい推論キーを作成します。一度だけ表示されるシークレットを返します。
or_key_update	名前／無効状態／上限／limit_reset／expires_at を更新します。
or_key_delete	キーを完全に削除します。
or_guardrail_create	ガードレールを作成します。
or_guardrail_update	ガードレールを更新します。
or_guardrail_delete	ガードレールを削除します。
or_guardrail_assign_keys / _unassign_keys	推論キーへのガードレールの一括割り当て／解除。
or_guardrail_assign_members / _unassign_members	組織メンバーへのガードレールの一括割り当て／解除。

例 — 1 日の上限を設定した一時キーを作成する

> Create a key called "scratch" with a $0.50 daily limit that expires in 30 days.

[Claude calls or_key_create with:
  name="scratch",
  limit=0.50,
  limit_reset="daily",
  expires_at="2026-05-25T00:00:00Z"]

Created key **scratch**
Hash: f7a3...
Limit: $0.5 (resets daily)
Expires: 2026-05-25T00:00:00Z

Secret: `sk-or-v1-...`
⚠️ This secret cannot be retrieved later — store it now.

例 — コストの急増を調査する

> Why did my OpenRouter spend jump yesterday?

[Claude calls or_activity with date="2026-04-24", aggregate="by_model"]

Activity: 47 rows | total $0.8570 | 305 req
By model (top 5):
- xiaomi/mimo-v2-flash      $0.5240 | 178 req | 24 rows
- anthropic/claude-haiku-4.5 $0.2105 | 39 req  | 5 rows
- ...

例 — アカウント全体に適用するガードレールにキーを紐付ける

> Cap our prod-bot key at the daily-$50 guardrail.

[Claude calls or_guardrails_list, finds gr_prod_daily_50,
 then or_guardrail_assign_keys with id="gr_prod_daily_50", hashes=["…"]]

Assigned guardrail `gr_prod_daily_50` to 1 key(s).

設計

サーバーは API の生フィールドを返します。「上限に近い」ものや「異常」を示したり、エージェントが何をすべきか判断したりはしません。それはエージェントの役割です。複合ツール（or_overview、or_guardrails_assignments）は複数のエンドポイントを 1 つのワークフロー応答にまとめますが、解釈は行いません。その理由は、本番環境の MCP サーバー（Stripe、GitHub、Linear）も同じパターンに従っているためです。

データの取り扱い

• Provisioning キーは環境変数 OPENROUTER_PROVISIONING_KEY から読み取られ、HTTPS 経由で https://openrouter.ai/api/v1/* にのみ転送されます。
• サーバーは再起動をまたいで状態を保持しません。セッション内の GET キャッシュ（/credits、/key、/keys、/keys/{hash} で TTL 60s）はメモリ内にのみ保持され、シャットダウン時に破棄されます。
• キーがエラーメッセージやツール出力に表示されることはありません（テストで検証済みです）。

開発

git clone https://github.com/oviron/openrouter-admin-mcp.git
cd openrouter-admin-mcp
npm install
npm run build      # compile TypeScript + chmod +x build/index.js
npm test           # vitest, 84 unit tests, mocked fetch

プロジェクトの構成：

src/
  client.ts            # OpenRouterClient — fetch wrapper, retry, in-session cache
  index.ts             # MCP server entry — registers tool groups
  tools/
    credits.ts         # or_credits, or_current_key
    keys.ts            # or_keys_list, _get, _create, _update, _delete
    activity.ts        # or_activity (5 modes incl. by_key)
    overview.ts        # or_overview composite
    generation.ts      # or_generation
    models.ts          # or_models, _model_get, _model_endpoints, _models_user, _zdr_endpoints
    guardrails.ts      # or_guardrails_list/_get/CRUD/bulk-assign + composite assignments
    organization.ts    # or_org_members
test/
  client.test.ts, credits.test.ts, keys.test.ts,
  activity.test.ts, overview.test.ts, generation.test.ts,
  models.test.ts, guardrails.test.ts, organization.test.ts,
  registration.test.ts, helpers.ts, smoke.test.ts

ライセンス

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