mcpField
T
token-lens

token-lens

Local
github.com/mdfifty50-boopAI & Agents0Updated 27w ago
Repository

About token-lens

token-lens is an MCP server for measuring and reducing context-window token use, aimed at developers managing tool-definition overhead. It estimates costs, compresses schemas, and recommends changes based on tool usage.

Key features

  1. 01Analyze token costs of tool definitions
  2. 02Recommend tools for a task
  3. 03Compress tool schemas
  4. 04Track loaded and called tools
  5. 05Generate context optimization reports

Use cases

  1. 01Measure MCP tool overhead in a context window
  2. 02Select tools for a specific task
  3. 03Find tools to remove based on call history

MCP support

The MCP server provides clients with tools for budget analysis, tool selection, schema compression, usage tracking, and optimization reports. It also exposes a guide to reducing context-window overhead as a resource.

Configuration

Local server config is the same for every client. Copy it into your client’s MCP config file.

mcp.json · Universal config
{
  "mcpServers": {
    "mdfifty50-boop-token-lens": {
      "command": "npx",
      "args": [
        "-y",
        "token-lens-mcp"
      ]
    }
  }
}
Run commandnpx -y token-lens-mcp

Local servers need a runtime on your machine (e.g. Node.js 18+). Config file locations differ by client; see your client’s docs.

Packages
npmtoken-lens-mcp0.1.2

Tools

No tool list yet

Local servers expose tools only once running on your machine, and the maintainer has not provided a tool list.

Details

From the project README

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 claude_desktop_config.json:

{
  "mcpServers": {
    "token-lens": {
      "command": "npx",
      "args": ["token-lens-mcp"]
    }
  }
}
Claude Code
claude mcp add token-lens -- npx token-lens-mcp

Tools

audit_context_budget

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.

optimize_tool_loading

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.

analyze_session_usage

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

Params:

  • session_id — Unique session identifier
  • action — "register_tool" | "log_call" | "report"
  • tool_name — Tool name (required for register_tool/log_call)
  • tool_tokens — Token cost (for register_tool, 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:

  • usage_history — Array of {tool_name, call_count, last_used_days_ago}

Scoring: never_used (priority 3) > not_used_30_days (priority 2) > rarely_used (priority 1)

Returns: Removal candidates with reasons and estimated token savings.

get_optimization_report

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

Comments

Markdown supported

New to MCP?

From what the protocol is to installing your first server, these answers cover most first questions.

An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.