grok-budget-mcp

A small, local MCP server (stdio) that lets a Grok Build CLI agent ask "how much of my SuperGrok / Grok Build weekly usage pool is left, and when does it reset?" — the same figure the interactive TUI shows under /usage (alias /cost).

Part of Hobelbank, a set of projects on building software in the age of AI.

Today an agent has no first-class way to get that number: /usage is TUI-only, grok -p "/usage" is treated as a prompt, and the ACP x.ai/billing method is not exposed over grok agent stdio. This server reads your existing grok login session and returns the figures as JSON.

What it does

Both tools take no input. Each call re-reads auth.json 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):

{
  "used_percent": 42.5,
  "remaining_percent": 57.5,
  "products": [
    { "product": "GrokBuild", "used_percent": 61.25, "remaining_percent": 38.75 },
    { "product": "GrokChat", "used_percent": 7, "remaining_percent": 93 }
  ],
  "period_type": "USAGE_PERIOD_TYPE_WEEKLY",
  "period_start": "2026-09-28T01:53:09.930537+00:00",
  "period_end": "2026-10-05T01:53:09.930537+00:00",
  "on_demand_cap": 2500,
  "on_demand_used": 120,
  "source": "cli-chat-proxy:/v1/billing?format=credits",
  "fetched_at": "2026-10-01T19:00:00.000Z",
  "warning": null
}

Mapping rules: numbers are never invented. If creditUsagePercent is omitted but a complete current period is present, it is reported as 0 (proto3 JSON omits zero values) with a warning. A product row without usagePercent is reported with null percents and a warning. A response with only monthly fields is not relabelled as weekly. If neither usage nor a period can be parsed, 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: agent-activity

Token handling (read-only)

• Reads $GROK_HOME/auth.json if GROK_HOME is set, else ~/.grok/auth.json — the file written by grok login.

• Picks the OIDC / grok login entry (preferring issuer https://auth.x.ai, ignoring bare API-key entries) and uses its key field as the Bearer token; expires_at is checked locally.

• Never refreshes the token, never writes auth.json, never calls an auth endpoint. If the session is expired or rejected, it tells you to run grok login (or simply use the Grok CLI, which refreshes its own session).

• 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://cli-chat-proxy.grok.com/v1/billing?format=credits
Authorization: Bearer <key from auth.json>
X-XAI-Token-Auth: xai-grok-cli
Accept: application/json

The base URL can be overridden with GROK_CLI_CHAT_PROXY_BASE_URL (same variable the Grok CLI honours, e.g. https://grok-proxy.example.com/v1); the server then calls <base>/billing?format=credits.

Install / build

Requires Node.js 22+.

git clone https://github.com/pihme/grok-budget-mcp.git
cd grok-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 auth files)
npm run smoke      # optional: start the server over stdio, list tools, call get_budget once with YOUR session

Optionally put the grok-budget-mcp binary on your PATH with npm link (or npm install -g github:pihme/grok-budget-mcp).

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

Wiring into Grok Build

Via the CLI (everything after -- is the server command):

grok mcp add grok-budget -- node /path/to/grok-budget-mcp/dist/index.js
# or, after `npm link`:
grok mcp add grok-budget -- grok-budget-mcp

Or directly 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

Then 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. User scope is enough; no env is needed. See the official Grok Build MCP docs.

A good agent instruction: "Before starting long or expensive work, call grok-budget__get_budget once; if remaining_percent (or the GrokBuild product's) is low, tell me and ask before continuing."

Not covered

• Not the Management API / console prepaid balance, and not per-request cost_in_usd_ticks — those are different ledgers.

• No Auto Top Up management, no grok.com scraping, no caching.

Background

Design notes and the research behind this server: SPEC.md. Community prior art that documents the endpoint and the auth.json shape (not endorsements): SergioComeron/GrokUsageBar, marcelocantos/claudia docs/grok-usage-billing.md, robinebers/openusage, ColumbusLabs/QuotaKit.

Contributing

Issues and ideas are welcome: see Contributing. Website and handbook: pihme.github.io/grok-budget-mcp.

How this project is built

grok-budget-mcp is developed agent-first. AI coding agents write all code, tests, and documentation, and review each other's changes, under human direction: specs, design decisions, and acceptance based on observed behaviour and test results. No human reads the code line by line. This is a deliberate choice. Quality rests on automated tests, CI, and independent agent review.

Evaluate the code against your own requirements before you depend on it. Found a problem? Open an issue.

License

MIT. Third-party software installed with it, and its licenses: THIRD_PARTY_NOTICES.md.