openrouter-admin-mcp

MCP server for the OpenRouter management API — programmatic control of credits, inference keys, guardrails, organization members, and usage analytics from inside Claude Code, Claude Desktop, Cursor, or any MCP-compatible client.

Read-only by default. Destructive write operations are gated behind an opt-in env flag.

This is not an inference proxy. It uses an OpenRouter Provisioning API key, which can manage your account but cannot make completion calls.

Why

OpenRouter's UI is solid for one-off tweaks, but checking spend across keys, drilling into per-model/per-day usage, configuring account-wide guardrails, or rotating limits requires a lot of clicking. This server exposes those operations as MCP tools — Claude can answer "what burned my credits this week?", "create a temporary key with a $0.30 daily cap", or "bind the new prod key to our daily-$50 guardrail" in a single turn.

Features

26 tools wrapping the OpenRouter management API:

• or_overview — one-shot dashboard: credits + active keys (with reset/expiration) + today's UTC burn by model.
• Inference key CRUD including limit_reset (daily/weekly/monthly) and expires_at.
• Guardrails CRUD — account-wide spending limits with provider/model allowlists, ZDR enforcement. Bulk-assign to keys or org members.
• Activity drill-down — aggregate by_model, by_day, by_provider, or by_key. Token-level breakdown (prompt / completion / reasoning) per row.
• Generation lookup — fetch any single inference call by gen-… id (cost, tokens, latency, finish reason).
• Model & endpoint discovery — current pricing per 1M tokens, per-provider uptime, ZDR-compliant endpoints.

Plumbing: HTTP retry on 429/5xx with Retry-After support, in-session GET cache, write invalidation. Returns raw fields — interpretation is left to the agent.

Install

One-click

Replace the placeholder sk-or-v1-... with your real key after install.

Manual

Run via npx (no install needed) or install globally:

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

Configuration

Create a Provisioning key at https://openrouter.ai/settings/provisioning, then add the server to your MCP client config.

Claude Code (~/.claude.json) or Claude Desktop (claude_desktop_config.json):

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

Restart your client to load the server. By default this gives read-only access — to enable key creation, mutation, and deletion, see Enabling write tools below.

Enabling write tools

Destructive operations (or_key_create, or_key_update, or_key_delete) are disabled by default to prevent accidental key mutation through prompt-injected tool calls. Add OPENROUTER_ADMIN_ALLOW_WRITE to your env block to enable them:

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

The server logs which mode it started in:

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

Read tools (or_overview, or_credits, or_current_key, or_keys_list, or_key_get, or_activity) are always available regardless of this flag.

Tools

Read (always available)

| Tool | Purpose | |---|---| | or_overview | One-shot dashboard: credits + active keys + today's burn by model. | | or_credits | Account balance: total purchased, total used, remaining. | | or_current_key | Metadata of the Provisioning key the server is using. | | or_keys_list | All inference keys with usage, limits, reset cadence, expiration. | | or_key_get | Detailed view of one key by hash. | | or_activity | Usage for the last 30 UTC days. Filters: date, api_key_hash, user_id. Aggregations: none, by_model, by_day, by_provider, by_key. | | or_generation | Fetch a single inference call by its gen-… id (cost, tokens, latency, finish reason). | | or_models | Model catalog with per-1M pricing, context length, modalities. Filterable. | | or_model_get | Full details for one model id. | | or_model_endpoints | Per-provider endpoints for a model: pricing, uptime, status. | | or_models_user | Models filtered by your account's privacy/guardrail settings. | | or_zdr_endpoints | ZDR-compliant endpoints for privacy-constrained workflows. | | or_guardrails_list | All guardrails: limit_usd, reset, allow/block lists, ZDR. | | or_guardrail_get | Full details for one guardrail. | | or_guardrails_assignments | Composite — which keys/members are bound to which guardrail. | | or_org_members | Members of the OpenRouter organization (Management-key + org account). |

Write (opt-in via OPENROUTER_ADMIN_ALLOW_WRITE=1)

| Tool | Purpose | |---|---| | or_key_create | Create a new inference key. Returns the one-time secret. | | or_key_update | Update name / disabled / limit / limit_reset / expires_at. | | or_key_delete | Permanently delete a key. | | or_guardrail_create | Create a guardrail. | | or_guardrail_update | Update a guardrail. | | or_guardrail_delete | Delete a guardrail. | | or_guardrail_assign_keys / _unassign_keys | Bulk-(un)assign a guardrail to inference keys. | | or_guardrail_assign_members / _unassign_members | Bulk-(un)assign a guardrail to org members. |

Example — create a daily-capped temporary key

> 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.

Example — diagnose a cost spike

> 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
- ...

Example — bind a key to an account-wide guardrail

> 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).

Design

The server returns raw API fields. It does not flag what's "near limit", what's an "anomaly", or what the agent should do — that's the agent's job. Composite tools (or_overview, or_guardrails_assignments) merge multiple endpoints into one workflow response, but they don't interpret. Rationale: production MCP servers (Stripe, GitHub, Linear) follow the same pattern.

Data handling

• The Provisioning key is read from the OPENROUTER_PROVISIONING_KEY environment variable and forwarded only to https://openrouter.ai/api/v1/* over HTTPS.
• The server is stateless across restarts. An in-session GET cache (60s TTL on /credits, /key, /keys, /keys/{hash}) is held in memory only and dropped on shutdown.
• The key never appears in error messages or tool output (verified by tests).

Development

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

Project layout:

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

License

MIT — see LICENSE.