Content
# mcp-context-budget
Measure and grade the **context-token cost** of an MCP server's tool surface.
Every tool an MCP server exposes (its name, description and JSON input schema) is
injected into the model's context on every turn. A server with forty verbose
tools can quietly burn thousands of tokens before the user has typed a word.
That cost is invisible in most workflows and it is the one thing a good MCP
server should keep lean. `mcp-context-budget` makes it visible: it connects to a
live server over stdio, adds up the token footprint of the whole tool surface,
grades it from A to F against a budget, and tells you exactly what to trim.
Zero third-party dependencies. Pure standard-library Python. MIT licensed.
> Part of a small MCP-quality toolchain: correctness (`mcp-conformance-kit`),
> surface stability (`mcp-surface-diff`), security hygiene (`mcp-server-audit`),
> performance (`mcp-load-lab`), and an aggregate grade (`mcp-scorecard`).
> This tool adds the missing dimension: **context efficiency**.
## Why context budget matters
The 2026 MCP roadmap calls out progressive tool discovery precisely because
large tool surfaces do not scale: they crowd the context window, raise latency
and cost, and make the model slower to pick the right tool. Before you reach for
progressive discovery, it helps to know how heavy your surface actually is, and
which tools are the offenders. That is what this tool reports.
## Install
```bash
pip install mcp-context-budget
# optional, for precise token counts instead of the heuristic:
pip install "mcp-context-budget[tiktoken]"
```
Or run straight from a checkout with no install at all:
```bash
python -m mcp_context_budget --help
```
## Quickstart
A sample server is bundled so you can try it immediately:
```bash
python -m mcp_context_budget --budget 4000 -- python examples/sample_server.py
```
```
MCP Context Budget
==================
Grade: A Score: 91.5/100 Estimation: heuristic
Total: 615 tokens across 4 tools (15.4% of 4000 budget)
Avg/tool: 153.8 Redundancy: 12.0%
Breakdown footprint 100 | redundancy 64 | verbosity 94 | schema 100
Heaviest tools:
tool tokens desc schema props
search_flights 287 100 171 10
book_flight 168 48 106 9
get_weather 123 47 51 2
ping 37 6 9 0
Findings:
[duplicated_text] get_weather, search_flights, book_flight: shared text wastes 24 tokens: 'Rate limits apply and requests may be throttled.'
...
```
Point it at any real server by putting that server's launch command after `--`:
```bash
python -m mcp_context_budget --budget 3000 -- npx -y @modelcontextprotocol/server-filesystem /tmp
```
## What it measures
| Dimension | Weight | What it looks at |
|---|--:|---|
| Footprint | 50% | Total tokens of the tool surface against your `--budget` |
| Redundancy | 20% | Boilerplate repeated across tool and parameter descriptions |
| Verbosity | 20% | Mean description length per tool |
| Schema | 10% | Mean property count and nesting per tool |
The four dimensions combine into a 0-100 score and an A-F grade. The report also
lists **findings**: the heaviest tools, over-long descriptions, oversized
schemas, and the exact duplicated sentences that waste the most tokens.
Token counting defaults to a portable `~4 chars per token` heuristic. Pass
`--mode tiktoken` (with the optional dependency installed) for exact counts; it
falls back to the heuristic automatically if `tiktoken` is not present.
## Output formats
```bash
# machine-readable, for dashboards or further processing
python -m mcp_context_budget --format json -- python examples/sample_server.py
# a Markdown report, e.g. to drop into a PR comment
python -m mcp_context_budget --format markdown -- python examples/sample_server.py
# a shields.io endpoint badge you can host and reference from a README
python -m mcp_context_budget --badge badge.json -- python examples/sample_server.py
```
## Use it as a CI gate
Fail the build when a server drifts past your context budget or below a grade:
```bash
python -m mcp_context_budget \
--budget 4000 --max-tokens 4000 --min-grade B \
-- python your_server.py
```
Exit codes: `0` pass, `2` over `--max-tokens`, `3` below `--min-grade`,
`4` could not talk to the server.
```yaml
# .github/workflows/context-budget.yml
- name: Check MCP context budget
run: |
pip install mcp-context-budget
mcp-context-budget --budget 4000 --min-grade B -- python your_server.py
```
## How it works
1. Spawn the server, complete the MCP handshake (`initialize` then
`notifications/initialized`), and page through `tools/list`.
2. Serialize each tool the way a client would present it to the model, and
estimate its token cost, split across name, description and schema.
3. Detect boilerplate shared across descriptions, score the four dimensions,
and render the grade, findings, and optional badge.
Everything runs locally over stdio. Nothing is sent anywhere.
## Library use
```python
from mcp_context_budget import fetch_tools, analyze
tools = fetch_tools(["python", "examples/sample_server.py"])
report = analyze(tools, budget=4000)
print(report["grade"], report["total_tokens"])
```
## Development
```bash
python -m unittest discover -s tests -v
```
## Licence
MIT. Contributions welcome.
MCP Store