Openrouter Admin README
The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Openrouter Admin listing page.
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) andexpires_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, orby_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:
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):
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:
The server logs which mode it started in:
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
Example — diagnose a cost spike
Example — bind a key to an account-wide guardrail
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_KEYenvironment variable and forwarded only tohttps://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
Project layout:
License
MIT — see LICENSE.