mcp-budget 0.1.0

Spending guard for AI agents — wraps any MCP server with budget limits and loop detection

mcp-budget

A spending guard for AI agents. Wraps any MCP server with hard call limits and loop detection — your AI won't spend more than you allow.

The problem

AI agents calling tools can run up costs fast. A coding agent in a loop can burn through hundreds of API calls in minutes. Existing dashboards show you the damage after it happens. mcp-budget is the circuit breaker that trips before the next call.

How it works

mcp-budget sits between your AI client (Claude Desktop, Claude Code, Cursor, etc.) and your MCP servers as a transparent proxy. It counts every tool call and blocks the agent when a limit is hit — no changes needed to the MCP server itself.

Client (Claude/Cursor) → mcp-budget → your MCP server
                            ↓
                      budget tracker
                      loop detector
                      circuit breaker

Install

pip install mcp-budget

Quick start

# Create a config with sensible defaults
mcp-budget init

# See your limits and current usage
mcp-budget status

Setting budgets

Set limits on any timeframe — mix and match as many as you want:

mcp-budget set 60 per minute      # burst protection
mcp-budget set 500 per hour       # hourly cap
mcp-budget set 2000 per day       # daily cap
mcp-budget set 10000 per week     # weekly cap
mcp-budget set 50000 per month    # monthly cap
mcp-budget set 200 per session    # per-session cap

Friendly aliases work too — daily, weekly, monthly, mins, hrs, etc.

mcp-budget set 2000 daily         # same as "per day"
mcp-budget remove hour            # drop a limit
mcp-budget warn 90                # warn at 90% usage (default: 80%)
mcp-budget reset daily            # reset today's counter

Wiring it up

Add mcp-budget in front of any MCP server command in your client config. The -- separates mcp-budget options from the server command.

Claude Desktop / Claude Code / Cursor:

{
  "mcpServers": {
    "my-server": {
      "command": "mcp-budget",
      "args": ["--", "npx", "-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
    }
  }
}

With a custom config path:

{
  "mcpServers": {
    "my-server": {
      "command": "mcp-budget",
      "args": ["--config", "/path/to/config.json", "--", "npx", "-y", "your-mcp-server"]
    }
  }
}

What gets enforced

• Budget limits — hard caps on tool calls per minute, hour, day, week, month, or session. When a limit is hit, the agent gets a clear error and stops.
• Loop detection — catches agents stuck in a loop calling the same tool repeatedly. Two modes: exact match (same tool + same arguments) and name-only match (same tool, any arguments).
• Near-limit warnings — logged when usage crosses a configurable threshold (default 80%), so you can see it coming.

Security

• Counter files are HMAC-signed — an agent with filesystem access can't edit its own budget counters without detection. Tampered files fail closed (treated as if the limit is already hit).
• Error messages to agents are deliberately vague — no exact counts or limits are leaked.
• All substantive MCP methods are metered: tools/call, resources/read, and prompts/get.

Status check

$ mcp-budget status

Budget usage:

  Minute    [#####--------------------]     12 / 60
  Session   [############-------------]     98 / 200
  Day       [################---------]    812 / 1,000 << NEAR LIMIT
  Week      [######-------------------]  1,203 / 5,000
  Month     [##-----------------------]  3,891 / 20,000

  Warning: day budget is at 81% — 188 calls remaining

  Loop breaker: 10 identical / 20 same-tool
  Warn at: 80%

Config file

Stored at ~/.mcp-budget/config.json. You can edit it directly or use the CLI commands above.

{
  "budgets": [
    {"limit": 60, "window": "minute"},
    {"limit": 200, "window": "session"},
    {"limit": 1000, "window": "day"},
    {"limit": 5000, "window": "week"},
    {"limit": 20000, "window": "month"}
  ],
  "loop_threshold": 10,
  "name_only_loop_threshold": 20,
  "warn_at_percent": 80,
  "log_file": "",
  "enabled": true
}

Requirements

• Python 3.10+
• Works on Windows, macOS, and Linux

License

MIT