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.
Strongest · Documentation 16/20 Weakest · Security and permissions 9/20
Static review · not runListed 2026-09-18
Read the FMRS scoring method →Runtime：Node.js 22+
TOKEN_OPTIMIZER_CACHE_DIR
Directory path for cache storage; optional, defaults to ~/.token-optimizer-mcp.
TOKEN_OPTIMIZER_MODE
Controls behavior: off disables optimization/enforcement, enforce vetoes expensive built-in calls; default is assist.
TOKEN_OPTIMIZER_PROXY
Set to 0 to disable the compression proxy routing.
TOKEN_OPTIMIZER_COMPRESSION
Compression preset: balanced, aggressive, conservative, or lossless; default balanced.
TOKEN_OPTIMIZER_PROXY_KNOWLEDGE
Set to 0 to disable injecting project knowledge into the cached prefix.
TOKEN_OPTIMIZER_HARVEST
Set to 0 to turn off model-based semantic harvest; with no credential it reports off:no-key.
TOKEN_OPTIMIZER_HARVEST_ENDPOINT
Point at a local model endpoint so semantic harvest runs free and private on-machine.
TOKEN_OPTIMIZER_MANAGED_CLIENTS
Set to 0 before installation to skip shell activation and managed client commands.
TOKEN_OPTIMIZER_PROXY_CAPTURE
Opt-in request-body capture writing plaintext request content to the named directory.
TOKEN_OPTIMIZER_LOG_DIR
Log directory; defaults to ~/.token-optimizer/logs or .token-optimizer/logs when a state directory is set.
TOKEN_OPTIMIZER_LOG_MAX_BYTES
Per-file log rotation size cap; default 5 MiB.
TOKEN_OPTIMIZER_LOG_MAX_FILES
Maximum number of retained log files; default 40.
TOKEN_OPTIMIZER_LOG_RETENTION_DAYS
Log retention period in days; default 14.
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"
}
}
}
}
Shown for Claude Code. Other clients may use a different file or key (VS Code uses "servers") — the configurator below converts it.
{
"servers": {
"token-optimizer": {
"command": "npx",
"args": [
"-y",
"@ooples/token-optimizer-mcp@latest"
],
"env": {
"TOKEN_OPTIMIZER_CACHE_DIR": "/path/to/cache"
}
}
}
}
Goes in your project's .vscode/mcp.json (VS Code uses a "servers" key).
claude mcp add token-optimizer -e TOKEN_OPTIMIZER_CACHE_DIR=/path/to/cache -- npx -y @ooples/token-optimizer-mcp@latest
Run it in a terminal; replace any <…> placeholders with your own values first.
Check that the token-optimizer tools (e.g. smart_read, token_audit) appear in your client's tool list, then run npx token-optimizer-doctor to confirm the hooks actually refuse a large read and the server answers; issuing a token_audit request that returns results also proves the connection works.
Once connected, you can ask your AI assistant things like:
No matching tools
Listed from the project's documentation, not tested by this site.
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.
Upstash's official server providing up-to-date third-party library docs for AI coding assistants
AI-powered NPM package analysis MCP server
An independent control layer that gives AI coding agents budgets, brakes, and receipts
GitHub's official MCP server for managing repos, issues, PRs, and workflows via natural language
Source revision d474b6a060b3 Data synced 2026-11-02 Read the FMRS scoring method