Skip to main content
Glama

claude-usage-mcp

Zero-dependency MCP server (Node.js >= 18, stdio) that reports your Claude subscription usage: 5-hour session and weekly limits (percent used, reset time).

It reads the OAuth token Claude Code stores in ~/.claude/.credentials.json (or CLAUDE_CODE_OAUTH_TOKEN) and calls GET https://api.anthropic.com/api/oauth/usage, the same source /usage uses. The endpoint is undocumented and may change.

Install

git clone https://github.com/tqk2811/claude-usage-mcp
claude mcp add --scope user claude-usage -- node /path/to/claude-usage-mcp/src/index.js

Quick check without MCP: node src/index.js --once

Related MCP server: claude-usage-mcp

Tool

get_usage — args: raw (include raw API response), force (bypass 30s cache).

Cache & concurrency

All server processes (one per Claude Code session) share a 30s cache file and a lock file in %TEMP%/claude-usage-mcp (or $TMPDIR/claude-usage-mcp), so concurrent calls make a single API request. If a refresh fails (e.g. HTTP 429) the last cached value is returned and marked stale.

5-hour session: 2% used, resets 11/18/2026, 8:40:00 AM (in 4h 24m)
Weekly (all models): 77% used, resets 11/18/2026, 8:00:00 PM (in 15h 44m)

Environment

  • CLAUDE_CODE_OAUTH_TOKEN — use this token instead of the credentials file.

  • CLAUDE_CONFIG_DIR — alternative Claude config directory.

  • CLAUDE_USAGE_CACHE_DIR — shared cache/lock directory.

  • CLAUDE_USAGE_DEBUG — log each real API call to stderr.

License

MIT

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      Not graded
      maintenance
      Provides real-time visibility into Claude Pro and Max subscription usage limits directly within Claude Code by utilizing local OAuth tokens. It enables users to monitor session and weekly usage across different models and receive alerts regarding rate-limiting status.
      4
      -
    • A
      license
      A
      quality
      C
      maintenance
      Reports your Claude subscription usage (5-hour and weekly limits) with a forecast and velocity recommendation, using Claude Code's existing OAuth session without requiring an API key.
      2
      4
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Gives the model visibility into the same 5-hour session, weekly, and per-model usage percentages shown in Claude Code, along with reset times. It also lets a project cap how much of the weekly limit may be spent via start/check/end budget tools that report OK, LOW, or OVER_BUDGET.
      1
      MIT