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:

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

Or via npx:

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

Tool

get_usage

Takes no arguments. Returns the current usage snapshot as 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.