TokenLens

Token intelligence layer for AI editors — analyze conversations, estimate costs, detect waste, and generate optimized prompts.

Quick Start

npm install
cp .env.example .env   # fill in your values
npm run build
npm start              # HTTP server on port 3000
npm run stdio          # stdio transport for Claude Desktop

MCP Tools

Tool	Description
analyze_conversation	Token count, cost estimate, waste detection
improve_prompt	Rewrite vague prompts into precise ones (local, no API)
smart_compress	Compress context by importance score
estimate_cost	Pre-flight cost estimate across all models
get_budget_status	Daily token budget and alert level
weekly_summary	Weekly usage vs last week
export_report	Markdown report saved to ~/.tokenlens/reports/

REST Endpoints (Chrome Extension)

POST /analyze-direct      Analyze a conversation (no auth)
POST /improve-prompt      Local prompt improvement (no auth)
POST /improve-prompt-ai   AI-powered prompt improvement (user API key)
POST /generate-prompt     AI prompt generation (user API key)
GET  /dashboard           Web UI
GET  /health              Health check

Configuration

Copy .env.example to .env and set:

PORT=3000
ADMIN_SECRET=<strong-random-secret>

AI provider keys are not required on the server — the Chrome Extension passes the user's own key per-request. Server-side keys are only needed if you add server-managed AI features.

Security

Your API keys are never stored on our servers. All keys are stored locally on your device only.

• The Chrome Extension saves API keys to browser localStorage — they never leave your machine
• The /generate-prompt and /improve-prompt-ai endpoints receive your key only for the duration of the API call and do not log or persist it
• The MCP server stores session analytics in a local SQLite database (~/.tokenlens/sessions.db) — no data is sent to external services
• Set a strong ADMIN_SECRET in your .env before exposing the server to any network

Hosted Server

The production server is available at:

https://tokenlens-mcp-production.up.railway.app

Endpoint	URL
Health	https://tokenlens-mcp-production.up.railway.app/health
SSE (MCP)	https://tokenlens-mcp-production.up.railway.app/sse
Dashboard	https://tokenlens-mcp-production.up.railway.app/dashboard
Chrome Extension default server URL	https://tokenlens-mcp-production.up.railway.app

Claude Desktop Setup

Option A — Hosted (recommended): connect via SSE to the production server.

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "tokenlens": {
      "url": "https://tokenlens-mcp-production.up.railway.app/sse",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}

Option B — Local stdio: run the server on your own machine.

{
  "mcpServers": {
    "tokenlens": {
      "command": "node",
      "args": ["/path/to/TokenLens MCP/dist/stdio.js"]
    }
  }
}