Token Analyzer MCP

Precise token counting and context efficiency analysis for MCP (Model Context Protocol) servers. Optimize your Claude Code setup by analyzing token consumption and identifying optimization opportunities.

Features

🔍 Comprehensive Token Analysis

• Real-time MCP Server Scanning: Automatically discovers and analyzes all configured MCP servers
• Incremental Impact Analysis: Shows how each server affects your total token budget
• Schema Complexity Measurement: Analyzes tool definitions for optimization opportunities
• Context Window Optimization: Tracks usage against 200k token context limit

📊 Multiple Analysis Modes

• Full Analysis: Complete token breakdown with detailed recommendations
• Quick Estimation: Fast overhead estimation without server connections
• Configuration Audit: Validate MCP setup and server accessibility
• Health Check: Verify analyzer dependencies and permissions

🎯 Optimization Intelligence

• Scenario Planning: Compare "what-if" optimization scenarios
• Smart Recommendations: Prioritized suggestions based on impact analysis
• Complexity Scoring: Identify overly complex tool schemas
• Usage Pattern Detection: Find verbose descriptions and optimization opportunities

📈 Professional Reporting

• Multi-format Export: JSON, CSV, and formatted text reports
• Visual Context Tracking: Color-coded overhead warnings
• Incremental Impact Tables: Step-by-step token accumulation analysis
• Executive Summaries: Quick overview for decision making

Installation

npm install -g token-analyzer-mcp

Quick Start

Analyze Your Current Setup

# Complete analysis with recommendations
token-analyzer-mcp analyze

# Quick overhead estimation
token-analyzer-mcp quick

# Check MCP configuration
token-analyzer-mcp config

# Verify analyzer setup
token-analyzer-mcp doctor

Export Detailed Results

# Save complete analysis to files
token-analyzer-mcp analyze \
  --output analysis.json \
  --report report.txt \
  --csv data.csv

Usage Examples

Basic Analysis

$ token-analyzer-mcp analyze

🔍 MCP Token Analyzer v1.0.0
Analyzing MCP server token consumption...

📋 Phase 1: Analyzing MCP Configuration
   ✅ Found 8 servers in ~/.claude/claude_desktop_config.json
   ✅ 6 active servers to analyze

🔌 Phase 2: Extracting Server Schemas
   ✅ document-organizer: 12 tools extracted
   ✅ conversation-search: 15 tools extracted
   ✅ claude-telemetry: 8 tools extracted

🔢 Phase 3: Measuring Token Impact
   ✅ Token analysis complete

📊 Phase 4: Incremental Impact Analysis
   ✅ Incremental analysis complete

Configuration Check

$ token-analyzer-mcp config

📋 MCP Configuration Analysis

✅ Configuration found: ~/.claude/claude_desktop_config.json
Total servers: 8

Configured Servers:
  • document-organizer (mcpServers) - ACTIVE
  • conversation-search (mcpServers) - ACTIVE
  • claude-telemetry (mcpServers) - ACTIVE
  • playwright (mcpServers) - DISABLED

Analysis Results

Token Usage Overview

┌─────────────────┬────────────┬────────────┐
│ Component       │ Tokens     │ Percentage │
├─────────────────┼────────────┼────────────┤
│ Built-in Tools  │ 2,250      │ 1.13%      │
│ MCP Servers     │ 8,540      │ 4.27%      │
│ Total Overhead  │ 10,790     │ 5.40%      │
│ Available       │ 189,210    │ 94.60%     │
└─────────────────┴────────────┴────────────┘

Incremental Impact Analysis

┌──────┬────────────────────┬─────────┬───────┬──────────────┐
│ Step │ Server             │ Tokens  │ Tools │ Cumulative % │
├──────┼────────────────────┼─────────┼───────┼──────────────┤
│ 1    │ document-organizer │ 3,240   │ 12    │ 2.75%        │
│ 2    │ conversation-search│ 2,890   │ 15    │ 4.19%        │
│ 3    │ claude-telemetry   │ 1,860   │ 8     │ 5.12%        │
│ 4    │ github-integration │ 550     │ 6     │ 5.40%        │
└──────┴────────────────────┴─────────┴───────┴──────────────┘

Configuration Requirements

The analyzer automatically discovers MCP configurations from standard locations:

• ~/.claude/claude_desktop_config.json
• ~/.config/claude-desktop/claude_desktop_config.json
• Windows: %APPDATA%/Claude/claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Supported Configuration Formats

{
  "mcpServers": {
    "document-organizer": {
      "command": "document-organizer-mcp",
      "args": [],
      "disabled": false
    }
  }
}

Optimization Recommendations

The analyzer provides actionable recommendations:

High Priority

• Token Overhead > 10%: Consider lazy loading or server reduction
• Complex Schemas: Simplify tool definitions or break into smaller tools
• Heavy Servers: Review servers consuming >2000 tokens

Medium Priority

• Verbose Descriptions: Reduce description length while maintaining clarity
• Unused Tools: Disable servers with low utilization
• Schema Optimization: Flatten nested object structures

Low Priority

• Naming Conventions: Use shorter but descriptive tool names
• Documentation: Add examples instead of lengthy descriptions

Advanced Features

Scenario Analysis

Compare optimization scenarios:

• Current Configuration: Baseline token usage
• Without Heaviest Server: Impact of removing the largest consumer
• Top 3 Only: Keep only the most valuable servers
• 50% Optimized: Simulated optimization results

Export Options

# Detailed JSON for integration
token-analyzer-mcp analyze --output detailed.json

# CSV for spreadsheet analysis
token-analyzer-mcp analyze --csv servers.csv

# Formatted report for documentation
token-analyzer-mcp analyze --report optimization-plan.txt

Programmatic Usage

import { IncrementalImpactAnalyzer } from 'token-analyzer-mcp';

const analyzer = new IncrementalImpactAnalyzer();
const results = await analyzer.performCompleteAnalysis();

console.log(`Total overhead: ${results.tokens.totalOverhead.overheadPercentage}%`);

Performance Considerations

• Connection Timeout: 10 seconds per server (configurable)
• Retry Logic: Up to 2 retry attempts for failed connections
• Memory Usage: Minimal overhead, designed for continuous monitoring
• Caching: Results can be cached for comparison over time

Troubleshooting

Common Issues

No MCP configuration found

# Check configuration locations
token-analyzer-mcp doctor

# Verify file permissions
ls -la ~/.claude/claude_desktop_config.json

Server connection failures

# Test individual server
node /path/to/server/index.js

# Check server logs
token-analyzer-mcp analyze --debug

High token consumption

# Identify heavy servers
token-analyzer-mcp analyze --summary

# Get optimization recommendations
token-analyzer-mcp analyze --report optimization.txt

Development

# Clone repository
git clone https://github.com/cordlesssteve/token-analyzer-mcp.git
cd token-analyzer-mcp

# Install dependencies
npm install

# Run tests
npm test

# Run analyzer locally
node src/index.js analyze

Architecture

src/
├── index.js                 # CLI interface
├── IncrementalImpactAnalyzer.js  # Main analysis engine
├── TokenMeasurementEngine.js     # Token counting logic
├── MCPConfigurationAnalyzer.js   # Configuration discovery
├── MCPSchemaExtractor.js         # Server schema extraction
└── ReportGenerator.js            # Report formatting

API Reference

IncrementalImpactAnalyzer

• performCompleteAnalysis(): Execute full token analysis
• analyzeTokenImpact(servers): Measure token consumption
• analyzeIncrementalImpact(tokens): Calculate cumulative impact
• generateRecommendations(analysis): Create optimization suggestions

TokenMeasurementEngine

• countServerTokens(server): Analyze individual server tokens
• analyzeSchemaComplexity(schema): Calculate complexity metrics
• measureBaselineTokens(): Get built-in tool overhead
• calculateTotalOverhead(servers): Compute total token usage

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Make your changes with tests
4. Run the test suite: npm test
5. Submit a pull request

Guidelines

• Follow existing code style
• Add tests for new features
• Update documentation
• Ensure backward compatibility

License

MIT License - see LICENSE file for details.

Support

• Documentation
• Issues
• Discussions
• Changelog

---

Optimize your Claude Code setup with precise token analysis!