内容
# claude-usage-mcp
一个小型的 [MCP](https://modelcontextprotocol.io) 服务器，用于报告您的 **Claude 使用情况** — 5 小时和每周限制窗口 — 带有 **预测** 和 **速度建议**。无需 API 密钥：它重用 Claude Code 已经存储在您机器上的 OAuth 会话，与 Claude Code 自己的 `/usage` 命令完全一样。
## 工作原理
1. 从 `~/.claude/.credentials.json` （或 macOS 钥匙串项目 `Claude Code-credentials`）读取 Claude Code 的 OAuth 凭证，并在需要时刷新访问令牌。
2. 调用未公开的使用端点 `GET https://api.anthropic.com/api/oauth/usage`，带有 `Authorization: Bearer <token>` 和 `anthropic-beta: oauth-2025-04-20`。响应包含 `five_hour`、`seven_day` 和 `seven_day_opus`，每个都有 `utilization` （0–100）和 `resets_at`。
3. 由于 Anthropic 的边缘指纹识别 TLS 握手并拒绝 Node 的 `fetch` 返回 `403 "Request not allowed"`，服务器首先尝试 `fetch`，然后 **回退到系统 `curl` 二进制文件** （该文件是可接受的）。`curl` 随 Windows 10+、macOS 和 Linux 一起提供。设置 `CLAUDE_USAGE_FORCE_CURL=1` 以直接跳转到 `curl`。
> 您必须通过 Claude Code （`claude`）登录才能使其工作。
## 工具
### `get_usage`
无参数。返回所有可用的窗口，包含：
`utilization`、`resetsAt`、`remainingHours`、`projectedEndUtilization` （如果您按照当前速度进行，则在重置时达到的值）、`exhaustAt` （如果您愿意，什么时候达到 100%）和 `velocityRecommendation`。
### `get_velocity`
参数 `window`：`"5h"`、`"weekly"` 或 `"weekly_opus"`。返回该窗口的速度建议和预测。
## 速度建议（0–120%）
一个数字，告诉您可以有多快。它比较了 *可持续速度* （恰好在重置时完成配额的速率）与您的 *当前平均速度*：
- **100%** — 全速。以您的当前速度，您将在窗口重置时恰好达到限制。
- **< 100%** — 您应该减慢到的当前速度分数，以免过早耗尽。例如，`40%` = 大约以当前速度的 40% 进行。
- **> 100%** （上限为 **120%**）— 您有足够的余量，可以按照这个速度消耗配额。尽全力吧。
5 小时和每周窗口分别评估，因此您将独立获得 `5h` 和 `weekly` 速度。
每个窗口的数学运算（长度 `L` = 5h 或 168h，利用率 `u`%，重置于 `R`）：
```
elapsed = now - (R - L)
remaining = R - now
rate = u / elapsed # % per hour
forecast = u / (elapsed / L) # % at reset if pace continues
exhaustAt = now + (100 - u) / rate # only if forecast > 100
velocity = ((100 - u) / remaining) / rate * 100 # clamped to [0, 120]
```
## 安装和构建
```bash
npm install
npm run build
```
## 使用 MCP 客户端注册
Claude Desktop （`claude_desktop_config.json`），或任何 stdio MCP 客户端：
```json
{
"mcpServers": {
"claude-usage": {
"command": "node",
"args": ["/absolute/path/to/claude-usage-mcp/dist/index.js"]
}
}
}
```
## 注意事项
- 使用端点是 **未公开的**，可能会在没有通知的情况下更改或消失 — 请将其视为尽力而为。
- 服务器可以读取您的 Claude Code OAuth 令牌（Claude Code 自己使用的相同文件）。它从不将它们发送到任何地方，只发送到Anthropic自己的端点，并通过 `stdin` 配置文件将 bearer 令牌传递给 `curl`，因此它永远不会出现在进程列表中。
- 速度使用已过去窗口的 *平均* 速度（每次调用一个快照）。它是一个指南，而不是保证；在重置前突然加速仍然可能超过限制。
## License
MIT
