Token Lens MCP server

token-lens-mcp

MCP server for analyzing and optimizing context window token usage. MCP tool definitions consume 40-72% of context windows before any user work begins — this server helps you measure, compress, and eliminate that waste.

Install

npx token-lens-mcp

Claude Desktop

Add to claudedesktopconfig.json:

{
  "mcpServers": {
    "token-lens": {
      "command": "npx",
      "args": ["token-lens-mcp"]
    }
  }
}

Claude Code

claude mcp add token-lens -- npx token-lens-mcp

Tools

auditcontextbudget

Analyze the token cost of your MCP tool definitions. Estimates tokens per tool using chars/4 approximation on the full JSON definition.

Params:

• tools — Array of {name, description, schema} objects

Returns: Per-tool token cost (sorted by cost), total tokens, percentage of 128K/200K/1M context windows.

optimizetoolloading

Given a task description, recommend the minimal set of tools needed. Uses keyword matching and category relevance scoring.

Params:

• task_description — What you're trying to accomplish
• available_tools — Array of {name, description, category?}

Returns: Recommended tools sorted by relevance, excluded tools, estimated tokens saved.

compress_schema

Compress verbose tool schemas to reduce token usage.

Params:

• tool_name — Name of the tool
• schema — JSON Schema object to compress
• level — "light" | "medium" | "aggressive"

Levels:

• light — Remove descriptions under 20 chars
• medium — Shorten descriptions to 50 chars, remove examples
• aggressive — Strip all descriptions, keep only types and required fields

Returns: Compressed schema, original/compressed token counts, savings percentage.

analyzesessionusage

Track which tools are actually called vs loaded during a session.

Params:

• session_id — Unique session identifier
• action — "registertool" | "logcall" | "report"
• toolname — Tool name (required for registertool/log_call)
• tooltokens — Token cost (for registertool, default 50)

Report returns: Loaded vs used counts, waste percentage, unused tools ranked by token cost.

suggest_removals

Identify tools that can be safely removed based on usage patterns.

Params:

• usagehistory — Array of {toolname, callcount, lastuseddaysago}

Scoring: neverused (priority 3) > notused30days (priority 2) > rarely_used (priority 1)

Returns: Removal candidates with reasons and estimated token savings.

getoptimizationreport

Full context window health check combining audit, removal suggestions, and compression recommendations.

Params:

• tools — Array of tool definitions
• usage_history — Optional usage history array

Returns: Executive summary with health grade (excellent/good/fair/poor), audit results, removal suggestions, compression opportunities, and actionable recommendations.

Resources

token-lens://tips

Best practices guide for reducing MCP context window bloat, including schema design tips, token budget guidelines, and dynamic tool loading strategies.

Development

npm install
npm test
npm run dev  # watch mode

License

MIT