
Token Optimizer MCP
Cut Claude Code context usage 60-90% via caching, Brotli compression, and smart tool replacements.
Add to your client
Copy the config for your MCP client and paste it into its config file.
npm install -g @ooples/token-optimizer-mcpPaste into ~/Library/Application Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"token-optimizer-mcp": {
"command": "node",
"args": [
"$NPM_PREFIX/lib/node_modules/@ooples/token-optimizer-mcp/dist/server/index.js"
]
}
}
}Step-by-step guides: Add to Claude Desktop · Add to Cursor · Add to Windsurf
Before you start
- Node.js 18+ (README mentions Node.js 20+ in the stack) and npm
- An MCP-compatible client (Claude Code, Claude Desktop, Cursor, Cline, GitHub Copilot, or Windsurf)
- Package installed globally via npm (@ooples/token-optimizer-mcp)
- Windows: PowerShell 5.1+ for the optional global hooks system
About Token Optimizer MCP
An MCP server that reduces context window usage by 60-90% through SQLite-backed caching, Brotli compression, and smart replacements for standard tools. It provides 60+ tools across caching, file operations, API/database access, build/test workflows, monitoring, and token analytics, using tiktoken for accurate token counting. Works as a standard MCP server for Claude Desktop, Cursor, Cline, GitHub Copilot, and Windsurf, and additionally offers a 7-phase global hooks system for Claude Code that optimizes every tool call automatically.
Tools & capabilities (65)
optimize_textCompress and cache text; primary tool for token reduction.
get_cachedRetrieve previously cached text by key.
compress_textCompress text using Brotli.
decompress_textDecompress Brotli-compressed text.
count_tokensCount tokens using tiktoken (GPT-4 tokenizer).
analyze_optimizationAnalyze text and return optimization recommendations.
get_cache_statsView cache hit rates and compression ratios.
clear_cacheClear all cached data (supports olderThan filtering).
smart_readRead files with caching and diff-based output (~80% token reduction).
smart_writeWrite files with verification and change tracking.
smart_editLine-based file editing with diff-only output (~90% reduction).
smart_grepSearch file contents with match-only output (~80% reduction).
smart_globFile pattern matching with path-only results (~75% reduction).
smart_diffGit diffs with diff-only output (~85% reduction).
smart_branchGit branch listing with structured JSON (~60% reduction).
smart_logGit commit history with smart filtering (~75% reduction).
smart_mergeGit merge management with conflict analysis (~80% reduction).
smart_statusGit status with status-only output (~70% reduction).
smart_api_fetchHTTP requests with caching and retry logic (~83% reduction on cache hits).
smart_cache_apiAPI response caching with TTL/ETag/event-based strategies.
smart_databaseDatabase queries with connection pooling and caching (~83% reduction).
smart_sqlSQL query analysis with optimization suggestions (~83% reduction).
smart_schemaDatabase schema analysis with intelligent caching.
smart_graphqlGraphQL query optimization with complexity analysis (~83% reduction).
smart_restREST API analysis with endpoint discovery (~83% reduction).
smart_ormORM query optimization with N+1 detection (~83% reduction).
smart_migrationDatabase migration tracking (~83% reduction).
smart_websocketWebSocket connection management with message tracking.
smart_buildTypeScript builds with diff-based change detection.
smart_testTest execution with incremental test selection.
smart_lintESLint with incremental analysis and auto-fix.
smart_typecheckTypeScript type checking with caching.
smart_installPackage installation with dependency analysis.
smart_dockerDocker operations with layer analysis.
smart_logsLog aggregation with pattern filtering.
smart_networkNetwork diagnostics with anomaly detection.
smart_processesProcess monitoring with resource tracking.
smart_system_metricsSystem resource monitoring with performance recommendations.
smart_cacheMulti-tier cache (L1/L2/L3) with 6 eviction strategies (~90% reduction).
cache_warmupIntelligent cache pre-warming with schedule support (~87% reduction).
cache_analyticsReal-time dashboards and trend analysis (~88% reduction).
cache_benchmarkPerformance testing and strategy comparison (~89% reduction).
cache_compression6 compression algorithms with adaptive selection (~89% reduction).
cache_invalidationDependency tracking and pattern-based invalidation (~88% reduction).
cache_optimizerML-based recommendations and bottleneck detection (~89% reduction).
cache_partitionSharding and consistent hashing (~87% reduction).
cache_replicationDistributed replication with conflict resolution (~88% reduction).
predictive_cacheML-based predictive caching with ARIMA/LSTM (~91% reduction).
alert_managerMulti-channel alerting (email, Slack, webhook) with routing (~89% reduction).
metric_collectorTime-series metrics with multi-source support (~88% reduction).
monitoring_integrationIntegrates external platforms (Prometheus, Grafana, Datadog) (~87% reduction).
custom_widgetDashboard widgets with template caching (~88% reduction).
data_visualizerInteractive visualizations with SVG optimization (~92% reduction).
health_monitorSystem health checks with state compression (~91% reduction).
log_dashboardLog analysis with pattern detection (~90% reduction).
smart_cronScheduled task management (cron / Windows Task Scheduler) (~85% reduction).
smart_userUser and permission management across platforms (~86% reduction).
smart_ast_grepStructural code search with AST indexing (~83% reduction).
get_session_statsSession-level token usage statistics and savings breakdown.
analyze_project_tokensProject-wide token analysis and cost estimation.
optimize_sessionCompress large file operations from the current session.
get_hook_analyticsToken usage breakdown by hook phase (PreToolUse, PostToolUse, etc.).
get_action_analyticsToken usage breakdown by tool/action (Read, Write, Grep, etc.).
get_mcp_server_analyticsToken usage breakdown by MCP server.
export_analyticsExport analytics data in JSON or CSV format with filtering.
What this server can do
Token Optimizer MCP provides tools for these capabilities — tap one to see every MCP server that does the same:
When to use it
- Slashing Claude Code / Claude Desktop context window usage on large codebases and long sessions
- Caching API and database responses so repeated calls cost minimal tokens
- Reading, editing, grepping, and diffing files with diff-only output to save tokens
- Measuring and reporting token savings per session, action, and MCP server
Security notes
Runs fully offline with no external dependencies. The npm postinstall script auto-detects and edits AI tool config files (Claude Desktop, Cursor, Cline, etc.), installs Claude Code global hooks that run on every tool call, and configures workspace trust and PowerShell execution policy; review what it changes before installing. Cached/compressed content is stored locally in an unencrypted SQLite database (~/.token-optimizer/cache.db), auto-cleaned after 7 days.
Token Optimizer MCP FAQ
Does it need an internet connection or API key?
No. The server runs fully offline with zero external dependencies and requires no authentication; it stores compressed content locally in SQLite.
Which clients does it support?
It works as a standard MCP server for Claude Desktop, Cursor, Cline, GitHub Copilot, and Windsurf. Claude Code additionally supports an optional 7-phase global hooks system that optimizes every tool call automatically.
How much token reduction can I expect?
The project reports 60-90% average reduction across 38,000+ real-world operations, with higher rates (83-95%) for cached API responses.
Where is cached data stored and is it cleaned up?
In a local SQLite database at ~/.token-optimizer/cache.db. Entries are automatically cleaned up after 7 days, and clear_cache can purge data manually.
Alternatives to Token Optimizer MCP
Compare all alternatives →Microsoft's official browser-automation MCP using Playwright's accessibility tree (no vision model).
Up-to-date, version-specific library documentation injected into your coding agent.
LSP-powered coding agent toolkit: semantic symbol search, references and structural edits.
Compare Token Optimizer MCP with: