Budget Guard MCP

Budget Guard MCP is a Model Context Protocol server that gives local agents a hard spend-control layer for LLM calls. It tracks token usage, computes estimated USD cost from a model price table, enforces daily and monthly caps, and returns explicit allowance decisions before an expensive call is made.

Why This Exists

Autonomous coding and research agents can burn API budget quickly when loops repeat, retries stack up, or a high-cost model is used for low-value work. A normal cost dashboard reports after the fact. Budget Guard is intended to sit in front of the action: an agent can call check_allowance before invoking an LLM and stop when the projected call would breach a cap.

Tools

• set_cap sets daily and/or monthly USD caps for a scope such as global, agent:lumen, or model:opus.
• record_usage records a completed LLM call with input/output/cache tokens and updates daily/monthly buckets.
• check_allowance estimates a planned call and returns allow=true/false with headroom and reason.
• usage_report returns current cap usage by scope.
• reset_period clears the current daily, monthly, or all usage buckets while preserving cap configuration.
• estimate_cost computes expected cost without recording anything.

Usage

npm install
node index.js

Example cap:

{
  "scope": "global",
  "daily_usd": 30,
  "monthly_usd": 300,
  "alert_thresholds": [0.5, 0.8, 0.95]
}

Example preflight:

{
  "scope": "agent:lumen",
  "model": "claude-opus-4-7",
  "input_tokens": 40000,
  "output_tokens": 4000
}

The response is intentionally machine-readable so an agent can stop, downgrade model, summarize context, or ask for approval before spending more.

Storage

State is written under ~/.local/share/budget-guard by default. The server uses local JSON files and JSONL event logs so operators can audit costs without a database. This is appropriate for a single workstation or one agent cluster sharing a home directory.

Monetization Path

This server is a practical MCPize product for teams running autonomous agents. It prevents budget overruns, documents spend by scope, and provides a clean control point for paid API usage. The value is measurable: avoided runaway loops and lower average cost per successful automation run.