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

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:

python -m mcp_context_budget --help

Quickstart

A sample server is bundled so you can try it immediately:

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 --:

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

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

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.

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

1. Serialize each tool the way a client would present it to the model, and

estimate its token cost, split across name, description and schema.

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

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

python -m unittest discover -s tests -v

Licence

MIT. Contributions welcome.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: shriramkv
• Source: shriramkv/mcp-context-budget
• License: MIT

Install and usage instructions live in the source repository linked above.