openrouter-admin

openrouter-admin-mcp

面向 OpenRouter 管理 API 的 MCP 服务，可在 Claude Code、Claude Desktop、Cursor 或任何兼容 MCP 的客户端中，以编程方式管理额度、推理密钥、护栏、组织成员和用量分析。

默认只读。破坏性写入操作需通过可选环境变量标志启用。

这不是推理代理。它使用 OpenRouter Provisioning API key，可管理你的账户，但无法发起补全请求。

为什么需要它

OpenRouter 的 UI 很适合进行零星调整，但要查看各密钥的支出、深入分析每个模型或每天的用量、配置账户级护栏，或轮换限额，都需要大量点击。此服务将这些操作封装为 MCP 工具——Claude 可以在一轮对话中回答“这周是什么消耗了我的额度？”，也可以“创建一个每日限额为 $0.30 的临时密钥”，或“将新的生产密钥绑定到每日限额 $50 的护栏”。

功能

封装 OpenRouter 管理 API 的 26 个工具：

• or_overview — 一站式仪表板：额度 + 活跃密钥（含重置时间和过期时间）+ 今日按模型统计的 UTC 消耗。
• 推理密钥 CRUD，包括 limit_reset（每日/每周/每月）和 expires_at。
• 护栏 CRUD——账户级支出限额，支持提供商/模型允许列表和 ZDR 强制执行。可批量分配给密钥或组织成员。
• 活动深入分析——按 by_model、by_day、by_provider 或 by_key 聚合。每行均提供 Token 级别的明细（提示词 / 补全 / 推理）。
• 生成查询——通过 gen-… ID 获取任意单次推理调用（费用、Token、延迟、结束原因）。
• 模型和端点发现——当前每 1M Token 的定价、各提供商的正常运行时间、符合 ZDR 的端点。

基础设施：针对 429/5xx 的 HTTP 重试（支持 Retry-After）、会话内 GET 缓存、写入时缓存失效。返回原始字段——由 Agent 负责解读。

安装

一键安装

安装后，将占位符 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）默认处于禁用状态。将 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	模型目录，包含每 1M 的定价、上下文长度和模态。支持筛选。
or_model_get	查看单个模型 ID 的完整详细信息。
or_model_endpoints	某个模型各提供商的端点：定价、正常运行时间、状态。
or_models_user	根据账户的隐私/护栏设置筛选模型。
or_zdr_endpoints	适用于隐私受限工作流的 ZDR 合规端点。
or_guardrails_list	所有护栏：limit_usd、重置设置、允许/阻止列表、ZDR。
or_guardrail_get	查看单个护栏的完整详细信息。
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	批量为组织成员分配/取消分配护栏。

示例 — 创建每日限额的临时密钥

> 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 字段。它不会标记哪些内容“接近限额”、哪些属于“异常”，也不会指示 Agent 应采取什么操作——这些都由 Agent 负责。复合工具（or_overview、or_guardrails_assignments）会将多个端点合并为一个工作流响应，但不会进行解读。原因：生产环境中的 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。