Metadata-Version: 2.4
Name: mcp-budget
Version: 0.1.0
Summary: Spending guard for AI agents — wraps any MCP server with budget limits and loop detection
License-Expression: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp>=1.0.0
Requires-Dist: anyio>=4.0.0
Dynamic: license-file

# 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

```bash
pip install mcp-budget
```

## Quick start

```bash
# 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:

```bash
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.

```bash
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:**

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

With a custom config path:

```json
{
  "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.

```json
{
  "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
