Precise token counting and context efficiency analysis for MCP servers
npm install @stacktown/token-analyzer-mcp


A tool for independent verification of token counts and context volume in Model Context Protocol (MCP) server configurations. Provides accurate token consumption analysis to validate and optimize your Claude Code setup.
This tool serves as an independent verification system for token usage in MCP configurations. Rather than relying on estimates or built-in metrics, it provides precise token counting and context volume analysis to:
- Verify actual token consumption vs. expected usage
- Validate context window utilization against the 200k token limit
- Identify servers consuming excessive tokens
- Provide independent confirmation of token optimization efforts
- Independent Token Verification - Accurate token counting separate from MCP server self-reporting
- Context Volume Analysis - Precise measurement of total context consumption
- MCP Configuration Scanning - Automatic discovery and analysis of configured servers
- Overhead Calculation - Breakdown of token usage by server and tool definitions
- Verification Reports - Detailed analysis for validating token usage claims
- Quick Estimation Mode - Fast overhead checking without full server connections
``bash`
npm install -g token-analyzer-mcp
bash
Perform independent token count verification
token-analyzer-mcp analyzeQuick context overhead verification
token-analyzer-mcp quickValidate MCP configuration setup
token-analyzer-mcp configVerify analyzer dependencies
token-analyzer-mcp doctor
`$3
`bash
Generate detailed verification report
token-analyzer-mcp analyze \
--output verification.json \
--report token-analysis.txt \
--csv usage-breakdown.csv
`Configuration Discovery
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$3
`json
{
"mcpServers": {
"server-name": {
"command": "node",
"args": ["path/to/server.js"],
"disabled": false
}
}
}
`Sample Verification Output
`
Token Analyzer - Independent Verification v1.0.0
Verifying MCP server token consumption...Phase 1: Configuration Discovery
✓ Found 6 servers in ~/.claude/claude_desktop_config.json
✓ 4 active servers to verify
Phase 2: Schema Extraction
✓ document-organizer: 12 tools extracted
✓ conversation-search: 15 tools extracted
✓ claude-telemetry: 8 tools extracted
Phase 3: Independent Token Verification
✓ Token verification complete
Verification Results:
Built-in Tools: 2,250 tokens (1.13%)
MCP Servers: 8,540 tokens (4.27%)
Total Overhead: 10,790 tokens (5.40%)
Available Context: 189,210 tokens (94.60%)
Status: ✅ Context usage within acceptable limits
`Commands
-
analyze - Full independent verification with detailed breakdown
- quick - Fast context overhead verification without server connections
- config - Validate MCP configuration accessibility and format
- doctor - Verify analyzer dependencies and permissionsVerification Accuracy
- Connection Timeout: 10 seconds per server to ensure accurate results
- Retry Logic: Up to 2 retry attempts for reliable token counting
- Independent Counting: Separate token calculation engine from MCP servers
- Cross-Validation: Multiple counting methods for accuracy verification
Troubleshooting
$3
`bash
Verify configuration locations
token-analyzer-mcp doctorCheck file permissions and accessibility
ls -la ~/.claude/claude_desktop_config.json
`$3
`bash
Test individual server accessibility
node /path/to/server/index.jsRun verification with debug output
token-analyzer-mcp analyze --debug
`$3
`bash
Generate detailed verification report
token-analyzer-mcp analyze --summaryCompare with previous verification results
token-analyzer-mcp analyze --report comparison.txt
`Development
`bash
Clone repository
git clone https://github.com/cordlesssteve/token-analyzer-mcp.git
cd token-analyzer-mcpInstall dependencies
npm installRun tests
npm testRun analyzer locally
node src/index.js analyze
`API Reference
$3
- performIndependentVerification() - Execute comprehensive token verification
- verifyServerTokens(servers) - Independently verify token consumption
- validateContextUsage(tokens) - Check context volume against limits
- generateVerificationReport(analysis) - Create verification documentation$3
- discoverConfigurations() - Find and validate MCP configuration files
- verifyServerAccessibility(server) - Test server connection and response
- validateConfigurationFormat(config) - Check configuration file structure
- calculateBaselineOverhead() - Measure built-in tool token consumptionContributing
1. Fork the repository
2. Create a feature branch:
git checkout -b feature-name
3. Add verification improvements and tests
4. Run the test suite: npm test`MIT License - see LICENSE file for details.