mcpweigh

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

Every MCP server you enable ships its tool names, descriptions and JSON schemas to the model on every request. Add a browser server, a GitHub server and a couple of others and you can burn 20–40k tokens before you type a word, which costs money, slows responses and pushes out the code you actually care about.

mcpweigh reads the MCP config you already have (Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, Gemini CLI, Codex CLI, Zed, OpenCode), starts each server, asks it for its tools, and tells you exactly where the tokens go, per server and per tool, with a budget check you can put in CI.

• Zero dependencies: pure Python 3.9+ standard library. Uses tiktoken (o200k_base) automatically if it is installed, otherwise a built-in estimator calibrated against it (typically within ~10%).
• Every transport: stdio, Streamable HTTP (with Mcp-Session-Id), and legacy HTTP+SSE.
• Every client config: auto-discovers user and project config files, understands JSONC, ${env:VAR}, ${workspaceFolder}, disabled servers, and Claude Code per-project scopes. The same server configured in several clients is weighed once.
• Actionable output: heaviest tools, description vs schema split, server instructions, bloated or undocumented tools, and tool names shared by several servers.
• CI friendly: --budget 8k exits 1 when you go over; --format json|markdown for bots and PR comments; --tools-json works fully offline.

Install

pipx install git+https://github.com/Yi-111-a/mcpweigh
# exact OpenAI-style token counts (optional):
pipx inject mcpweigh tiktoken

Or run it straight from a clone: python -m mcpweigh.

Usage

mcpweigh                          # weigh every server in every client config it can find
mcpweigh --list                   # just show what was discovered (never prints env values)
mcpweigh -c .cursor/mcp.json      # one config file, any supported format
mcpweigh -s github -s playwright  # only these servers
mcpweigh --context 200k           # show the share of a 200k-token window
mcpweigh --budget 8k              # exit 1 if the total is over 8,000 tokens

# one server, no config needed
mcpweigh -- npx -y @modelcontextprotocol/server-filesystem /tmp
mcpweigh --url https://example.com/mcp -H "Authorization: Bearer $TOKEN"
mcpweigh --url http://localhost:3001/sse --sse      # legacy SSE servers

# offline / CI: weigh a saved tools/list result
mcpweigh -- uvx my-server --dump snapshots/       # save raw tools/list JSON
mcpweigh --tools-json snapshots/my-server.json --budget 4k -f markdown

Example output

SERVER       TOOLS    TOKENS   SHARE
playwright      25      3762   54.0%  ###########.........
filesystem      14      1692   24.3%  #####...............
everything      13      1512   21.7%  ####................
TOTAL           52      6966

Heaviest tools:
     310  playwright/browser_take_screenshot  (desc 23, schema 275, 6 params)
     254  playwright/browser_emulate_media  (desc 32, schema 210, 5 params)
     ...

Server instructions (also injected into context):
     428  everything

~6966 tokens of tool definitions loaded into every request (tiktoken/o200k_base); 3.5% of a 200000-token context window
OVER BUDGET: 6966 > 5000

(Real numbers from examples/claude_desktop_config.json, measured in October 2026; server versions change.)

Where it looks

In CI

- run: pipx install git+https://github.com/Yi-111-a/mcpweigh
- run: mcpweigh -c .mcp.json --budget 10k --strict -f markdown >> "$GITHUB_STEP_SUMMARY"

If you build an MCP server, commit a tools/list snapshot and gate it with --tools-json snapshot.json --budget N so a verbose docstring never silently doubles your users’ token bill.

Exit codes

How it counts

Each tool is serialised the way clients forward it to model APIs, {"name", "description", "input_schema"} as compact JSON, and counted with o200k_base (or the estimator). Server instructions returned by initialize are counted too, because clients such as Claude Code put them in the system prompt. Clients add a little wrapper text of their own and different model families tokenize differently, so treat the numbers as close estimates for comparing servers and tracking regressions rather than as billing-exact figures.

Starting a stdio server runs its command, exactly as your MCP client would. Use --list first if you are unsure what a config will launch.

中文说明

mcpweigh 用来回答一个问题：你开的这些 MCP 服务器，每次请求要占掉多少上下文 token？ 它会自动读取 Claude Desktop、Claude Code、Cursor、VS Code、Windsurf、Gemini CLI、Codex、Zed、OpenCode 的 MCP 配置，逐个启动服务器（支持 stdio、Streamable HTTP、旧版 SSE），拉取 tools/list，按服务器和工具统计 token，指出最重的工具、描述与 schema 各占多少、缺描述或参数过多的工具，以及多个服务器之间重名的工具。

• 零依赖，Python 3.9+；装了 tiktoken 就用 o200k_base 精确计数，否则用内置估算（误差一般在 10% 以内）。
• --budget 8k 超预算时退出码为 1，可直接放进 CI；--tools-json 支持离线分析保存下来的工具列表。
• 常用：mcpweigh、mcpweigh --list、mcpweigh --context 128k、mcpweigh -- npx -y 。

License

MIT