Skip to main content
Glama
openrouter-admin-mcp

openrouter-admin-mcp

by oviron

openrouter-admin-mcp

npm version npm downloads CI MCP Registry Node License: MIT

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.

demo

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.

Related MCP server: proxyllm-mcp

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

Install in VS Code Install in Cursor

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.

Available Tools

16 tools
or_activityC

Show OpenRouter usage grouped by endpoint for the last 30 UTC days. Optional filters: date (YYYY-MM-DD), api_key_hash, user_id.

Inputs: date, limit, user_id, aggregate, +1 more.

or_creditsA

Show OpenRouter balance: total purchased, total used, remaining.

Inputs: no named parameters.

or_current_keyA

Show metadata of the Provisioning key the server is using (label, type, limits, usage).

Inputs: no named parameters.

or_generationA

Get details of a single inference call by its generation_id (returned by OpenRouter in completion responses, e.g. 'gen-abc123'). Returns cost, tokens, latency, finish reason, provider — useful when an agent needs to explain why a specific call cost what it did.

Inputs: id (required).

or_guardrail_getA

Get details of one guardrail by id: limit_usd, reset_interval, allowed/ignored providers/models, enforce_zdr.

Inputs: id (required).

or_guardrails_assignmentsA

One-shot view of all guardrail assignments: which keys and which org members are bound to which guardrail. Combines /guardrails/key-assignments and /guardrails/member-assignments.

Inputs: no named parameters.

or_guardrails_listA

List all OpenRouter guardrails (account-wide spending limits and provider/model allowlists).

Inputs: no named parameters.

or_key_getA

Get details of one OpenRouter inference key by hash.

Inputs: hash (required).

or_keys_listA

List all OpenRouter inference API keys with usage and limits.

Inputs: offset, include_disabled.

or_model_endpointsA

List all provider endpoints for a specific model (which providers serve it, their pricing, context length, uptime). Use this when picking the cheapest or most-stable provider for a model.

Inputs: slug (required), author (required).

or_model_getA

Get full details of a single model by id (e.g. 'anthropic/claude-opus-4.7'): description, context, modalities, pricing, supported parameters.

Inputs: id (required).

or_modelsA

List OpenRouter model catalog with pricing per 1M tokens, context length, and modalities. Use this to compare models or look up current prices. Filter via search/supported_parameters/output_modalities.

Inputs: search, output_modalities, supported_parameters.

or_models_userA

List models available to this account, respecting privacy/guardrail settings (differs from or_models which returns the full public catalog).

Inputs: no named parameters.

or_org_membersA

List members of the OpenRouter organization (when running under a Management key for an org account). Useful as input for guardrail member-assignments.

Inputs: limit, offset.

or_overviewA

One-shot dashboard: account credits, all active keys (with daily/weekly/monthly reset info), and today's UTC burn by model. Combines credits + keys + activity into a single call. Use this first when investigating cost or checking key health.

Inputs: no named parameters.

or_zdr_endpointsA

List ZDR-compliant model endpoints (Zero Data Retention). Useful for agents under privacy/compliance constraints.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 16 tools

    Disambiguation4/5

    Each tool targets a specific resource or view (models, keys, guardrails, usage), and the overview tool is purposefully distinct as a dashboard. The only potential confusion is between or_models_user and or_models, but descriptions clarify account-specific vs public catalog.

    Naming Consistency2/5

    All tools use the or_ prefix, but beyond that the naming is inconsistent: list/get suffixes appear on some resources but not others, and or_models_user reverses the expected resource-modifier order. This mixing of conventions requires careful reading to infer the pattern.

    Tool Count4/5

    16 tools is at the upper edge of the ideal range. Each tool covers a distinct read operation, so none feels redundant, but the count is slightly heavy for a server that only provides administrative reads.

    Completeness2/5

    The set is heavily skewed toward read-only operations: models, keys, guardrails, and usage can be queried, but there are no create, update, or delete operations for any resource. Given the 'admin' label, the lack of key/guardrail management actions is a significant gap.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      MCP server for ProxyLLM, the OpenAI-compatible LLM gateway, enabling live model catalogs, plan-savings calculations, routing key management, and autonomous account signup.
      9
      112 npm
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      A local MCP server exposing the OpenAI platform REST API as tools for file management, fine-tuning, inference, images, audio, batch processing, and organization usage/costs.
      -
    • A
      license
      A
      quality
      B
      maintenance
      MCP server for the LiteLLM proxy, enabling agents to administer resources like keys, teams, users, models, and proxy settings through risk-graded meta-tools.
      6
      MIT