claude-budget-mcp

A small, local MCP server (stdio) that lets a Claude Code agent ask "how much of my 5-hour and weekly usage limits is left, and when do they reset?" — the same figures the interactive /usage command shows for a Claude subscription (Pro, Max, Team, Enterprise).

Today an agent has no first-class way to get these numbers: /usage is interactive, and the status line's rate_limits only reach the status line script. This server reads your existing Claude Code login and returns the figures as JSON. It is the sister project of grok-budget-mcp.

What it does

One tool, get_budget, with no input. Each call re-reads the credentials file and makes exactly one HTTPS request (15 s timeout, no retries, no caching).

get_budget output

All fields are always present; anything the endpoint did not return is null and explained in warning.

Example (illustrative values):

{
  "session_used_percent": 24,
  "session_remaining_percent": 76,
  "session_resets_at": "2026-10-02T22:00:00.000000+00:00",
  "weekly_used_percent": 61.5,
  "weekly_remaining_percent": 38.5,
  "weekly_resets_at": "2026-10-06T08:00:00.000000+00:00",
  "windows": [
    { "window": "five_hour", "used_percent": 24, "remaining_percent": 76, "resets_at": "2026-10-02T22:00:00.000000+00:00" },
    { "window": "seven_day", "used_percent": 61.5, "remaining_percent": 38.5, "resets_at": "2026-10-06T08:00:00.000000+00:00" },
    { "window": "seven_day_opus", "used_percent": 12, "remaining_percent": 88, "resets_at": "2026-10-06T08:00:00.000000+00:00" }
  ],
  "subscription_type": "max",
  "source": "api.anthropic.com:/api/oauth/usage",
  "fetched_at": "2026-10-02T19:00:00.000Z",
  "warning": null
}

Mapping rules: numbers are never invented. A missing 5-hour or weekly window gives null fields and a warning. If no window with a utilization can be parsed at all, the tool returns an error.

Errors

Errors are returned as MCP tool errors (isError: true) with a code and a readable message:

Related MCP server: claude-usage-mcp

Token handling (read-only)

• Reads $CLAUDE_CONFIG_DIR/.credentials.json if CLAUDE_CONFIG_DIR is set, else ~/.claude/.credentials.json, the file Claude Code writes on /login.

• Uses claudeAiOauth.accessToken as the Bearer token; expiresAt is checked locally.

• Never refreshes the token, never writes the file, never calls an auth endpoint. Claude Code rotates the refresh token on every refresh, so an outside refresh could sign out your sessions.

• Never logs, prints or returns the token, the Authorization header, or the raw upstream body.

• No secrets go into MCP config env.

Request sent (once per tool call):

GET https://api.anthropic.com/api/oauth/usage
Authorization: Bearer <accessToken from .credentials.json>
anthropic-beta: oauth-2025-04-20
Accept: application/json
User-Agent: claude-budget-mcp/<version>

The base URL can be overridden with CLAUDE_BUDGET_MCP_BASE_URL (for tests or a proxy). The server identifies itself honestly; the endpoint is known to rate-limit clients that are not Claude Code more strictly, so call it once before expensive work rather than often.

Install / build

Requires Node.js 22+.

git clone https://github.com/pihme/claude-budget-mcp.git
cd claude-budget-mcp
npm install        # also builds dist/ via the prepare script
npm run build      # tsc -> dist/
npm test           # unit + stdio smoke tests (mocked fetch, fixture credentials)
npm run smoke      # optional: start the server over stdio, list tools, call get_budget once with YOUR login

Prebuilt alternative: each release has a claude-budget-mcp-X.Y.Z.tgz (built dist/, no build step); npm install -g ./claude-budget-mcp-X.Y.Z.tgz puts claude-budget-mcp on your PATH. Versions follow SemVer; nothing is published to npm.

Wiring into Claude Code

claude mcp add --scope user claude-budget -- node /path/to/claude-budget-mcp/dist/index.js
# or, with the binary on your PATH:
claude mcp add --scope user claude-budget -- claude-budget-mcp

Check it with claude mcp list or /mcp. The tool appears as mcp__claude-budget__get_budget. No env is needed. See the official Claude Code MCP docs.

A good agent instruction (for example in CLAUDE.md): "Before starting long or expensive work, call mcp__claude-budget__get_budget once; if session_remaining_percent or weekly_remaining_percent is low, tell me and ask before continuing."

Not covered

• macOS Keychain logins, CLAUDE_CODE_OAUTH_TOKEN from claude setup-token, API keys, Bedrock, Vertex, Foundry.

• Not API-key rate limits or Console spend — different ledgers.

• No dollar cost (Claude Code computes that on the client), no extra-usage spend, no caching or polling.

Background

Design notes and the research behind this server: SPEC.md. Community prior art that documents the endpoint (not endorsements): andrewleech cc-usage, FullFran/claudeops-tui, cship.

Contributing

Issues, ideas and pull requests are welcome: see Contributing. Website and handbook: pihme.github.io/claude-budget-mcp.

License

MIT