# claude-usage-mcp

An MCP server that reports your real Claude subscription usage — 5-hour
session window, weekly limit, and per-model limits — pulled from the same
endpoint Claude Code's `/usage` command uses.

## Requirements

- macOS or Linux
- Node.js 20+
- Claude Code logged in on a Pro, Max, or Team plan

This server reads Claude Code's own OAuth access token (from the macOS
Keychain, or `~/.claude/.credentials.json` as a fallback). It never asks for
or stores credentials itself.

## Install / configure

Add to your `.mcp.json`.

Local build:

```json
{
  "mcpServers": {
    "claude-usage": {
      "command": "node",
      "args": ["/path/to/claude-usage-mcp/dist/index.js"]
    }
  }
}
```

Or via npx:

```json
{
  "mcpServers": {
    "claude-usage": {
      "command": "npx",
      "args": ["-y", "@anatoly314/claude-usage-mcp"]
    }
  }
}
```

## Tool

### `get_usage`

Takes no arguments. Returns the current usage snapshot as JSON.

```json
{
  "session_5h": { "utilization_percent": 42, "resets_at": "2026-09-01T18:00:00Z" },
  "weekly_7d": { "utilization_percent": 61, "resets_at": "2026-09-05T00:00:00Z" },
  "model_limits": [
    {
      "model": "Opus",
      "kind": "weekly_scoped",
      "utilization_percent": 51,
      "resets_at": "2026-09-05T00:00:00Z",
      "is_active": true
    }
  ],
  "fetched_at": "2026-09-01T15:04:00Z",
  "stale": false
}
```

If a fetch fails, the last successful response is served instead with
`stale: true` and `stale_age_seconds` set.

## Notes

- This uses an undocumented Anthropic endpoint. It may change or break
  without notice.
- Responses are cached for 120 seconds; after a failed fetch, further
  requests back off for 60 seconds before retrying, to avoid hammering the
  API.
- Everything stays local — no data leaves your machine except the request to
  Anthropic's usage endpoint.