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.