claudeusage-mcp

An MCP server that gives you real-time visibility into your Claude Pro/Max subscription usage — directly inside Claude Code.

No API keys. No scraping. No browser automation. It reads the OAuth token that Claude Code already stores on your machine and calls Anthropic's usage endpoint to get the exact same data shown on claude.ai/settings/usage.

---

What it shows

| Metric | Description |
|--------|-------------|
| Current Session | 5-hour burst window utilization with reset countdown |
| Weekly Usage - All Models | 7-day rolling limit across all models |
| Weekly Usage - Opus Only | 7-day Opus-specific usage (Max plans) |
| Weekly Usage - Sonnet Only | 7-day Sonnet-specific usage |
| Extra Usage | Enabled/disabled, monthly limit, credits used |

MCP tool output (get_usage)

=== Claude Plan Usage ===
Current Session (5-hour window)

  ████████░░░░░░░░░░░░  37%

  Resets in 2h 14m (Sat Mar 22 07:59PM)
Weekly Usage - All Models (7-day) [HIGH]

  ██████████████████░░  89%

  Resets in 4d 3h (Wed Mar 26 05:00PM)
Weekly Usage - Opus Only

  N/A (not on your plan)
Weekly Usage - Sonnet Only

  ░░░░░░░░░░░░░░░░░░░░  1%

  Resets in 4d 3h (Wed Mar 26 08:59PM)
Extra Usage: Disabled
--- Color Grading ---

0-49% = GREEN (safe)  |  50-79% = ORANGE (moderate)  |  80-99% = RED (high)  |  100% = RATE LIMITED
(live data)

Rate-limited state

When any metric hits 100%, the output changes to show reset date and time:

Weekly Usage - All Models (7-day) [RATE LIMITED]
  XXXXXXXXXXXXXXXXXXXX  100%
  Resets in 1d (Mon Mar 24 05:00PM)

Statusline output

The included statusline script adds a third line to your Claude Code status bar with progress bars and color coding:

  Usage: Session █░░░░░░░░░ 13% | Weekly █████████░ 94% | Sonnet █░░░░░░░░░ 8%

When rate-limited:

  Usage: Session: RATE LIMITED, Resets in: 3h 37m (Sun Mar 22 07:59PM) | Weekly: RATE LIMITED, Resets in: 1d (Mon Mar 23 05:00PM)

Color grading

| Range | Color | Status |
|-------|-------|--------|
| 0-49% | Green | Safe |
| 50-79% | Orange | Moderate |
| 80-99% | Red | High |
| 100% | Red + text | RATE LIMITED with reset datetime |

Tools

| Tool | Purpose |
|------|---------|
| get_usage | Full dashboard — session, weekly, per-model, extra usage with progress bars |
| get_session_usage | Current 5-hour session window only |
| get_weekly_limits | 7-day limits with per-model breakdown (All, Opus, Sonnet) |
| check_rate_status | Am I about to be rate-limited? Returns LOW / MODERATE / HIGH / RATE LIMITED |

Requirements

- Node.js >= 18
- Claude Code logged in with a Pro or Max subscription
- macOS or Linux (reads credentials from Keychain or ~/.claude/.credentials.json)

Installation

Option 1: claude mcp add (recommended)

git clone https://github.com/OrelliusAI/claudeusage-mcp.git
cd claudeusage-mcp
npm install && npm run build
claude mcp add claudeusage -- node $(pwd)/dist/index.js

Restart Claude Code. Then ask "what's my usage?" or type /usage.

Option 2: Manual config

git clone https://github.com/OrelliusAI/claudeusage-mcp.git
cd claudeusage-mcp
npm install && npm run build

Add to your MCP config (.claude.json or project .mcp.json):

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

Optional: Statusline integration

Add usage data to your Claude Code statusline (always visible at the bottom):

```bash