token-optimizer-mcp
Advanced tools
Intelligent context window optimization for Claude Code - store content externally via caching and compression, freeing up your context window for what matters
Intelligent token optimization through caching and compression for Claude Code and Claude Desktop
Token Optimizer MCP is a Model Context Protocol (MCP) server that reduces context window usage through intelligent caching and compression. By storing compressed content externally in SQLite, the server removes tokens from your context window while keeping them accessible. The server provides tools to compress text, cache results, and analyze token usage - helping you maximize your available context window.
npm install
npm run build
The server is already configured in .mcp.json at the project root. To use it:
The server is configured in claude_desktop_config.json. To verify:
%APPDATA%\Roaming\Claude\claude_desktop_config.json includes:{
"mcpServers": {
"token-optimizer": {
"command": "node",
"args": [
"C:\\Users\\yolan\\source\\repos\\token-optimizer-mcp\\dist\\server\\index.js"
]
}
}
}
// Use the optimize_text tool to cache content externally
optimize_text({
text: "Your large text content here...",
key: "my-cache-key",
quality: 11 // 0-11, higher = better compression
})
// Result - compressed data is stored in SQLite, NOT returned in context
{
"success": true,
"key": "my-cache-key",
"originalTokens": 1500,
"compressedTokens": 450, // Tokens IF it were in context (not relevant)
"tokensSaved": 1050, // Context window savings (what matters)
"percentSaved": 70.5, // Based on compression + external storage
"originalSize": 6000,
"compressedSize": 1800, // Stored in SQLite
"cached": true
}
// Your context window now contains only the cache key (~50 tokens)
// instead of the original 1500 tokens - 96.7% reduction in context usage!
// Use the get_cached tool
get_cached({ key: "my-cache-key" })
// Result:
{
"success": true,
"key": "my-cache-key",
"text": "Your original text content...",
"fromCache": true
}
// Use the count_tokens tool
count_tokens({ text: "Your text here" })
// Result:
{
"tokens": 150,
"characters": 500
}
// Use the analyze_optimization tool
analyze_optimization({ text: "Your text here" })
// Result:
{
"tokens": {
"current": 1500,
"afterCompression": 450,
"saved": 1050,
"percentSaved": 70
},
"size": {
"current": 6000,
"compressed": 1800,
"ratio": 3.33,
"percentSaved": 70
},
"recommendations": {
"shouldCompress": true,
"reason": "Compression will provide significant token savings"
}
}
// Use the get_cache_stats tool
get_cache_stats({})
// Result:
{
"totalEntries": 15,
"totalSize": 45000,
"hits": 42,
"misses": 8,
"hitRate": 84.0,
"avgCompressionRatio": 3.2,
"totalTokensSaved": 12500
}
It's important to understand the difference between compression ratio and context window savings:
When you cache content using this MCP server:
Example: A 10,000 token API response is cached:
When you compress text without caching (using compress_text), the compressed data must be encoded as Base64 to be transmitted as text:
optimize_text which caches the compressed data externallyHigh Value Use Cases:
Lower Value Use Cases:
Original Text (10,000 tokens)
↓
Brotli Compress (82x ratio)
↓
Store in SQLite (~122 bytes)
↓
Return Cache Key (~50 tokens)
↓
RESULT: 9,950 tokens removed from context window
The key insight: The value is in external storage, not compression alone. Even with modest compression ratios, moving data out of your context window provides massive savings.
# Build the project
npm run build
# Run in development mode (watch)
npm run dev
# Run tests (when implemented)
npm test
# Run benchmarks (when implemented)
npm run benchmark
ISC
Built for optimal Claude Code token efficiency.
FAQs
Intelligent context window optimization for Claude Code - store content externally via caching and compression, freeing up your context window for what matters
The npm package token-optimizer-mcp receives a total of 86 weekly downloads. As such, token-optimizer-mcp popularity was classified as not popular.
We found that token-optimizer-mcp demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Security News
GPT-6 Astra hits 100% on ExploitBench and finds zero-days autonomously, while independent tests reveal scope violations and monitoring gaps.
Product
Socket can now send alerts and supply chain attack notifications to Microsoft Teams, with filters that route the right updates to each channel.
Security News
pnpm 12 rewrites the package manager in Rust, cutting install times by up to 90% while preserving pnpm 11 workflows and lockfiles.