mcp-context-cost

Analyze how many tokens your MCP server tool definitions consume on every LLM call.

Why it matters

Every MCP tool definition gets injected into every LLM request. The GitHub MCP server alone is 11K+ tokens. Stack 5 servers and you're burning 30K tokens — 23% of GPT-4o's context window — before your prompt even starts.

  Server                       Tools    Tokens  Score
  ──────────────────────────────────────────────────
  github                          41    11,075  HEAVY ⚠
  git                             28    10,724  HEAVY ⚠
  playwright                      22     3,883  OK
  filesystem                      14     2,437  OK
  memory                           9     1,601  LEAN ✓
  ──────────────────────────────────────────────────
  TOTAL                          114    29,720

  GPT-4o (128K)   23.2%  [###########.......................................]
  Verdict: Heavy load. Review top servers for schema bloat.

Install

pip install mcp-context-cost

Usage

# Scan a single server
mcp-cost -- npx -y @modelcontextprotocol/server-filesystem /tmp
mcp-cost -- docker run --rm -i ghcr.io/github/github-mcp-server

# Scan all servers from your config (Claude Desktop / Cursor / Claude Code)
mcp-cost --config

# Explicit config path
mcp-cost --config ~/.config/Claude/claude_desktop_config.json

# JSON output (for scripting / CI)
mcp-cost --json -- npx -y @modelcontextprotocol/server-memory
mcp-cost --json --config

Auto-detected config locations (in order):

• ~/.config/Claude/claude_desktop_config.json (Claude Desktop, Linux)
• ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
• ~/.cursor/mcp.json (Cursor global)
• .cursor/mcp.json (Cursor project)
• .mcp.json (Claude Code project)

Scores

Score	Tokens	Meaning
LEAN ✓	< 2K	Well-scoped server
OK	2K–8K	Normal range
HEAVY ⚠	8K–20K	Consider auditing schemas
BLOATED ✗	> 20K	Significant context drain

Token estimation

Uses tiktoken (cl100k_base) if already cached locally, otherwise falls back to len(text) // 4 which is accurate within ~10%.

Requirements

• Python 3.11+
• mcp package (installed automatically)

License

MIT