mcp-context-budget

# 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.