grok-budget-mcp

#What it is

grok-budget-mcp is a small, local MCP server that lets a Grok Build agent ask: how much of my SuperGrok / Grok Build weekly usage pool is left, and when does it reset? It answers with the same figure the interactive TUI shows under /usage, as JSON.

An agent has no first-class way to get that number today: /usage is TUI-only, and grok -p "/usage" is treated as a prompt. The server reads your existing grok login session, makes one HTTPS request per tool call and returns the figures. It never refreshes or writes the session.

Unofficial endpoint. The server calls the private route the Grok Build CLI itself uses for /usage. It is not a public xAI 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 xAI.

#Current status

Last updated 2 October 2026 · main@6b05cc3

All 49 tests pass on the main branch in continuous integration, on Node.js 22 and 24. Both tools work against a stand-in for the billing service: the budget tool returns the used and remaining share of the weekly pool, every product row, the reset time and the extra-usage figures, and the second tool returns the monthly credit units. One test starts the real server the way Grok Build does and calls a tool end to end. A missing or expired login, a rejected session, 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 grok-budget-mcp/v0.1.0. Releases are cut automatically after the tests pass and include a ready-built package.

The server depends on an endpoint that xAI does not document, so it can break whenever xAI changes it; it then reports a warning or an error instead of guessing. It never renews the login: when the session runs out, the user runs grok login again or simply uses the Grok CLI, which renews its own session. The tests use made-up sample responses, never the live service. It needs Node.js 22 or newer; older versions are no longer supported. There is no package on the npm registry, so it is installed from source or from the package attached to each release. There are no open issues.

#Key concepts

#Getting started

Needs Node.js 22+ and a Grok CLI that is logged in with grok login.

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

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

Wire it into Grok Build (everything after -- is the server command):

grok mcp add grok-budget -- node /path/to/grok-budget-mcp/dist/index.js

Or in ~/.grok/config.toml:

[mcp_servers.grok-budget]
command = "node"
args = ["/path/to/grok-budget-mcp/dist/index.js"]
startup_timeout_sec = 15
tool_timeout_sec = 30

Check it with grok mcp doctor grok-budget and /mcps in the TUI. The tools appear as grok-budget__get_budget and grok-budget__get_monthly_credits. A good agent instruction: “Before long or expensive work, call grok-budget__get_budget once; if 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 session. More in the readme and the official Grok Build 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; most tell you to run grok login.

#Architecture & layout

Grok Build starts the server as a child process and talks MCP over stdin/stdout. Per tool call the server reads auth.json without changing it and sends one GET /v1/billing?format=credits (or /v1/billing for monthly credits) with the session key as Bearer token. Diagnostics go to stderr only.