claude-budget-mcp

#What it is

claude-budget-mcp is a small, local MCP server that lets a Claude Code agent ask: how much of my 5-hour and weekly usage limits is left, and when do they reset? It answers with the same figures the interactive /usage command shows for a Claude subscription (Pro, Max, Team, Enterprise), as JSON.

An agent has no first-class way to get these numbers today: /usage is interactive, and the status line’s rate limits only reach the status line script. The server reads your existing Claude Code login, makes one HTTPS request per tool call and returns the figures. It never refreshes or writes the login.

Unofficial endpoint. The server calls the private route Claude Code itself uses for /usage. It is not a public Anthropic API and can change at any time; the server then fails loudly instead of guessing. Use it as a personal, local helper with your own account. Not affiliated with or endorsed by Anthropic.

#Current status

Last updated 2 October 2026 · main@e5ff717

All 29 tests pass on the main branch in continuous integration, on Node.js 22 and 24. The budget tool returns the used and remaining share of the 5-hour session window and of the weekly window, their reset times, every per-model window the service reports, and the plan type. One test starts the server the way Claude Code does and calls the tool end to end. A missing or expired login, rate limits, timeouts and changed responses come back as clear errors, and the tests check that the login file is never changed and the token never appears in a result. The latest release is claude-budget-mcp/v0.1.0. Releases are cut automatically after the tests pass.

The server has not yet been tried against the live service with a real login; the automated tests use made-up sample responses. It depends on an endpoint that Anthropic does not document, so it can break whenever Anthropic changes it, and it then reports a warning or an error instead of guessing. It never renews the login: when the token runs out, the user simply uses Claude Code, which renews its own login, or signs in again. It reads the login file Claude Code keeps on Linux, not the macOS Keychain. There is no package on the npm registry. There are no open issues.

#Key concepts

#Getting started

Needs Linux, Node.js 22+ and Claude Code logged in with a Claude subscription (/login). On macOS Claude Code keeps its login in the Keychain, which this version does not read.

git clone https://github.com/pihme/claude-budget-mcp.git
cd claude-budget-mcp
npm install        # also builds dist/ via the prepare script
npm test           # offline: mocked endpoint, synthetic credentials files

Or take the prebuilt package from the latest release (built dist/, no build step): npm install -g ./claude-budget-mcp-X.Y.Z.tgz puts claude-budget-mcp on your PATH. Nothing is published to npm.

Wire it into Claude Code (everything after -- is the server command):

claude mcp add --scope user claude-budget -- node /path/to/claude-budget-mcp/dist/index.js

Check it with claude mcp list or /mcp. The tool appears as mcp__claude-budget__get_budget. A good agent instruction, for example in CLAUDE.md: “Before long or expensive work, call mcp__claude-budget__get_budget once; if the session or weekly remaining percent is low, tell me and ask before continuing.”

npm run smoke is an optional manual check: it starts the server and calls get_budget once with your real login. More in the readme and the official Claude Code MCP docs.

#Tools & output

get_budget always returns every field; anything the endpoint did not send is null.

Errors

Returned as MCP tool errors (isError: true) with a code and a readable message; the login errors tell you to use Claude Code once or run /login.

#Architecture & layout

Claude Code starts the server as a child process and talks MCP over stdin/stdout. Per tool call the server reads .credentials.json without changing it and sends one GET /api/oauth/usage with the access token as Bearer token. Diagnostics go to stderr only.