mcp-context-budget

Your MCP servers eat the context window before you type anything. This tells you how much, and which one to drop.

Free, local, read-only. No account, no network call, no telemetry.

The problem this solves

Every MCP server you install injects its full tool schema into every request. There is no lazy loading in the protocol. A dozen servers can consume tens of thousands of tokens before your first message, and nothing in the client tells you this is happening — the agent just gets quietly worse.

Known incidents from public reports:

• Cloudflare's standard MCP server consumed 1.17M tokens in production, prompting a dedicated workaround.

• A practitioner measured 45K tokens for GitHub MCP alone — 22.5% of a 200K window.

• A 12-server setup reported the system prompt at 18,000 tokens before the user typed.

This tool measures your actual setup instead of quoting those numbers at you.

Related MCP server: mcp-checkup

Why measurement, not estimation

The config file only records how to start a server. The real cost lives in the tools/list payload, which changes with the server version and its runtime flags. Guessing from the config produces a confident wrong answer.

So this tool starts each stdio server, asks it for its tools, measures the payload, and shuts it down. That is the only honest method, and it takes a few seconds.

Install

Requires Python 3.8+. No dependencies.

git clone <repo> mcp-context-budget

Add to your MCP client config (claude_desktop_config.json, .cursor/mcp.json, or ~/.workbuddy/mcp.json):

{
  "mcpServers": {
    "mcp-context-budget": {
      "command": "python",
      "args": ["/absolute/path/to/mcp-context-budget/run.py"]
    }
  }
}

Tools

audit_context_budget

Full report: cost per server, cost per tool, findings with quantified savings, and a fix order.

How much of my context window are my MCP servers eating?

Optional arguments: window (200k default, or 128k/32k/16k), config (explicit path), show_tools (list the N most expensive tools per server).

rank_servers_by_cost

Just the ranking. Answers "which server should I remove first" in one line per server.

explain_token_cost

Measure an arbitrary schema or string before you publish a server of your own. Reports the CJK/ASCII split and shows how wrong the naive len/4 heuristic would be.

What it detects

Each finding carries an estimated token saving, so you can decide whether it is worth the edit.

What it does not do

• Does not edit anything. It never writes to your configs and never removes a server.

• Does not measure remote servers. URL-based (SSE / streamable HTTP) servers are listed as not probed rather than silently scored zero. Their cost is real but cannot be measured locally.

• Does not prove a bad agent is caused by schema cost. It quantifies one specific tax. If your schemas are 2% of the window, the cause is elsewhere and the report says so.

• Estimates, not exact tokenizer output. No tokenizer dependency, by design — that would triple install size and pin you to one model family. The estimator is calibrated to over-count slightly, because under-counting a budget is the failure that hurts.

Reading the verdict

Ten percent is the line where trimming is worth the afternoon. Twenty percent is where the agent is measurably worse than it was before you installed things.

Self-verification

Do not take the claims on faith:

python tests/selftest.py

28 checks, both directions: pathological schemas must be caught, and clean well-written servers must produce zero findings. The negative tests are the important half — a tool that cries wolf gets ignored, which is worse than no tool.

License

MIT.