Token Lens

io.github.mdfifty50-boopPublished by GitHub account mdfifty50-boopv0.1.2Updated Oct 24, 2026

Context window token analysis and budget management

VerifiedSTDIODesktop onlyDeveloper ToolsAI & ML

Overview

AI-generated overview

Local MCP server that measures and trims the context-window token cost of MCP tool definitions, schemas and session usage.

What you can do
  • Audit tool definitions for per-tool and total token cost and share of 128K/200K/1M windows
  • Recommend a minimal tool set for a task and estimate tokens saved
  • Compress JSON schemas at light, medium or aggressive levels and report savings
  • Track loaded versus called tools per session and rank unused ones by cost
  • Suggest tools safe to remove from usage history
  • Produce a combined health report with a grade and recommendations, plus a tips resource
When to use it
Useful when an assistant's context is crowded by many MCP tool definitions and you want to measure that overhead, cut schemas down, or decide which tools to drop.
Requirements
Runs locally over stdio via npx token-lens-mcp; Node.js with npx is needed. No authentication, environment variables or headers are declared.
Before you install
Token counts are estimates based on a chars/4 approximation, not a real tokenizer. Compression at medium or aggressive levels removes descriptions and examples, which can make tools harder for a model to use correctly. Tool definitions and usage history you pass in are processed by the local process.

Installation

In SourceWeft

  1. Open Token Lens in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

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

bash
npx token-lens-mcp

Claude Desktop

Add to claude_desktop_config.json:

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

Claude Code

bash
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

bash
npm installnpm testnpm run dev  # watch mode

License

MIT

Source: README.md at commit f0a843e

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.1.2LatestSep 16, 2026

Score

40% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts

    Declare a license in the repository or the registry entry.