Token Optimizer MCP is an unusually large scope project and a rare self-verifying one: it does not merely claim token savings, it ships the benchmark scripts, the losses, the excluded data and the unfinished studies alongside the wins. Its core value is twofold — compressing tool results and smart-reading files before they reach the model, and a local knowledge graph that fills itself in from real agent traffic. Against typical alternatives it is explicit about separating direct, materialized savings from causal graph evidence, and it renders an unmeasurable saving as unknown rather than zero.
What deserves caution: the many comparisons against the competitor HeadRoom are offline estimates using this repository's own reimplementation of their published design, not their shipped binary, and the author repeatedly states that superiority was not established and that several studies are incomplete. The graph's causal benefit remains Collecting. It also actively refuses tool calls and writes elided payloads to local spill files, both of which have real workflow and security implications. Best suited to developers willing to accept a more invasive integration and able to run the benchmarks themselves.
Token Optimizer MCP is a locally running MCP server that optimizes the context window of AI coding agents. Through caching, compression and smart file tools, it reduces token spend before tool results reach the model; the README claims a 60–90% cut.
It also maintains a cross-session local knowledge graph: nodes for files, symbols, tasks and findings, joined by edges such as derived_from, contains, supersedes, contradicts and related. Findings, decisions and dead ends accumulate as a side effect of working, then feed back the moment the agent touches a relevant file, so conclusions are not re-derived. Data stays local — no account, no telemetry, no hosted service.
The server speaks stdio and ships as the npm package @ooples/token-optimizer-mcp under the MIT license, which permits commercial use. The README documents 16 clients and separates an enforcing tier (10 clients with a pre-execution hook that can refuse a wasteful built-in call) from a rules tier (6 clients where optimized routing is mandatory via rules but cannot be vetoed). Benchmarks ship in the repository and can be regenerated, e.g. with node bench/compression/proof.mjs.
Claude Code: run /plugin marketplace add ooples/token-optimizer-mcp, then /plugin install token-optimizer@token-optimizer, then /reload-plugins.
MCP server only (any client): npx -y @ooples/token-optimizer-mcp@latest. Optionally set TOKEN_OPTIMIZER_CACHE_DIR to choose the cache directory; it defaults to ~/.token-optimizer-mcp.
Codex: codex plugin marketplace add ooples/token-optimizer-mcp, then codex plugin add token-optimizer@token-optimizer; or codex mcp add token-optimizer -- npx -y @ooples/token-optimizer-mcp@latest.
After installing, verify the hooks actually work with npx token-optimizer-doctor — it feeds a synthetic payload to the real hook binary and asserts a large read is refused and a small one is not. Ready-made config for all sixteen clients lives in the repository's integrations/ directory.
{
"mcpServers": {
"token-optimizer": {
"command": "npx",
"args": ["-y", "@ooples/token-optimizer-mcp@latest"],
"env": {
"TOKEN_OPTIMIZER_CACHE_DIR": "/path/to/cache"
}
}
}
}