Token Optimizer MCP is a Model Context Protocol (MCP) server that reduces context window usage by 60-90% through intelligent caching, compression, and smart tool replacements. By storing compressed content externally in SQLite and providing optimized alternatives to standard tools, the server helps you maximize your available context window. Production Results: 60-90% token reduction across 38,000
Add this skill
npx mdskills install ooples/token-optimizer-mcpComprehensive token optimization with 65 tools, proven 60-90% reduction, and automatic hook-based integration
Intelligent token optimization through caching, compression, and smart tooling for Claude Code and Claude Desktop
Token Optimizer MCP is a Model Context Protocol (MCP) server that reduces context window usage by 60-90% through intelligent caching, compression, and smart tool replacements. By storing compressed content externally in SQLite and providing optimized alternatives to standard tools, the server helps you maximize your available context window.
Production Results: 60-90% token reduction across 38,000+ operations in real-world usage.
# Run PowerShell as Administrator, then:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
# Install globally (hooks install automatically!)
npm install -g @ooples/token-optimizer-mcp
# Install globally (hooks install automatically!)
npm install -g @ooples/token-optimizer-mcp
That's it! The postinstall script will automatically:
Result: 60-90% token reduction across all operations!
Note: If automatic installation is skipped (e.g., in CI environments), you can manually run the installer:
powershell -ExecutionPolicy Bypass -File install-hooks.ps1bash install-hooks.shFor detailed platform-specific installation instructions, see docs/HOOKS-INSTALLATION.md.
Click to expand
Usage Example:
// Cache large content to remove it from context window
optimize_text({
text: "Large API response or file content...",
key: "api-response-key",
quality: 11
})
// Result: 60-90% token reduction
Click to expand
Optimized replacements for standard file tools with intelligent caching and diff-based updates:
Usage Example:
// Read a file with automatic caching
smart_read({ path: "/path/to/file.ts" })
// First read: full content
// Subsequent reads: only diff (80% reduction)
Click to expand
Intelligent caching and optimization for external data sources:
Usage Example:
// Fetch API with automatic caching
smart_api_fetch({
method: "GET",
url: "https://api.example.com/data",
ttl: 300
})
// Cached responses: 95% token reduction
Click to expand
Development workflow optimization with intelligent caching:
Usage Example:
// Run tests with caching
smart_test({
onlyChanged: true, // Only test changed files
coverage: true
})
Click to expand
Enterprise-grade caching strategies with 87-92% token reduction:
Usage Example:
// Configure multi-tier cache
smart_cache({
operation: "configure",
evictionStrategy: "LRU",
l1MaxSize: 1000,
l2MaxSize: 10000
})
Click to expand
Comprehensive monitoring with 88-92% token reduction through intelligent caching:
Usage Example:
// Create an alert
alert_manager({
operation: "create-alert",
alertName: "high-cpu-usage",
channels: ["slack", "email"],
threshold: { type: "above", value: 80 }
})
Click to expand
System-level operations with smart caching:
Usage Example:
// View session token usage
get_session_stats({})
// Result: Detailed breakdown of token usage by tool
Click to expand
Granular token usage analytics for pinpointing optimization opportunities:
Usage Example:
// Get per-hook analytics
get_hook_analytics({
startDate: "2025-01-01T00:00:00Z",
endDate: "2025-12-31T23:59:59Z"
})
// Result: Shows which hooks consume the most tokens
// Get per-action analytics
get_action_analytics({})
// Result: Shows which tools use the most tokens
// Export analytics as CSV
export_analytics({
format: "csv",
hookPhase: "PreToolUse"
})
// Result: CSV export filtered by PreToolUse hook
Key Features:
When global hooks are installed, token-optimizer-mcp runs automatically on every tool call:
┌─────────────────────────────────────────────────────────────┐
│ Phase 1: PreToolUse - Tool Replacement │
│ ├─ Read → smart_read (80% token reduction) │
│ ├─ Grep → smart_grep (80% token reduction) │
│ └─ Glob → smart_glob (75% token reduction) │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ Phase 2: Input Validation - Cache Lookups │
│ └─ get_cached checks if operation was already done │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ Phase 3: PostToolUse - Output Optimization │
│ ├─ optimize_text for large outputs │
│ └─ compress_text for repeated content │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ Phase 4: Session Tracking │
│ └─ Log all operations to operations-{sessionId}.csv │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ Phase 5: UserPromptSubmit - Prompt Optimization │
│ └─ Optimize user prompts before sending to API │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ Phase 6: PreCompact - Pre-Compaction Optimization │
│ └─ Optimize before Claude Code compacts the conversation │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ Phase 7: Metrics & Reporting │
│ └─ Track token reduction metrics and generate reports │
└─────────────────────────────────────────────────────────────┘
Based on 38,000+ operations in real-world usage:
| Tool Category | Avg Token Reduction | Cache Hit Rate |
|---|---|---|
| File Operations | 60-90% | >80% |
| API Responses | 83-95% | >75% |
| Database Queries | 83-90% | >70% |
| Build/Test Output | 70-85% | >65% |
Per-Session Savings: 300K-700K tokens (worth $0.90-$2.10 at $3/M tokens)
// Cache large content to remove from context window
const result = await optimize_text({
text: "Large API response or file content...",
key: "cache-key",
quality: 11
});
// Result: Original tokens removed, only cache key remains (~50 tokens)
// Retrieve later
const cached = await get_cached({ key: "cache-key" });
// Result: Full original content restored
// First read: full content
await smart_read({ path: "/src/app.ts" });
// Subsequent reads: only changes (80% reduction)
await smart_read({ path: "/src/app.ts" });
// First request: fetch and cache
await smart_api_fetch({
method: "GET",
url: "https://api.example.com/data",
ttl: 300
});
// Subsequent requests: cached (95% reduction)
await smart_api_fetch({
method: "GET",
url: "https://api.example.com/data"
});
// View token usage for current session
await get_session_stats({});
// Result: Breakdown by tool, operation, and savings
// Analyze entire project
await analyze_project_tokens({
projectPath: "/path/to/project"
});
// Result: Cost estimation and optimization opportunities
The automated installer detects and configures token-optimizer-mcp for:
No manual configuration needed - the installer automatically detects and configures all installed tools!
Cause: Caching very large files or many API responses
Solution:
Clear old entries:
await clear_cache({ olderThan: 7 }); // Clear entries older than 7 days
Reduce cache retention:
await smart_cache({
operation: "configure",
defaultTTL: 3600 // 1 hour instead of 7 days
});
Manually delete cache (nuclear option):
rm -rf ~/.token-optimizer/cache.db
If you encounter issues not covered here:
~/.claude-global/hooks/logs/dispatcher.log~/.claude-global/hooks/data/current-session.txtget_session_statsMIT License - see LICENSE for details
Built for optimal Claude Code token efficiency by the ooples team.
Install via CLI
npx mdskills install ooples/token-optimizer-mcpToken Optimizer MCP is a free, open-source AI agent skill. Token Optimizer MCP is a Model Context Protocol (MCP) server that reduces context window usage by 60-90% through intelligent caching, compression, and smart tool replacements. By storing compressed content externally in SQLite and providing optimized alternatives to standard tools, the server helps you maximize your available context window. Production Results: 60-90% token reduction across 38,000
Install Token Optimizer MCP with a single command:
npx mdskills install ooples/token-optimizer-mcpThis downloads the skill files into your project and your AI agent picks them up automatically.
Token Optimizer MCP works with Claude Code, Claude Desktop, Cursor, Vscode Copilot, Windsurf, Continue Dev, Gemini Cli, Amp, Roo Code, Goose. Skills use the open SKILL.md format which is compatible with any AI coding agent that reads markdown instructions.