Token Optimizer MCP

What it does

Token Optimizer MCP is a Node.js server that sits between a coding agent and the files and output it keeps pulling into its context. Its file tools (smart_read, smart_edit, smart_grep and the like) cache what they return, so reading an unchanged file again gives back a diff instead of the whole file, and searches come back as matches or paths only. Text the agent wants out of its window can be compressed and parked in a local cache with optimize_text and fetched back with get_cached or expand.

Alongside the cache it keeps a per-project knowledge graph that the agent writes to and reads from (wiki_write, wiki_read, wiki_query), so findings survive into later sessions, plus a set of audit tools that report token spend, prompt-cache waste and savings, per project or across the whole machine. Everything is stored on the user's own disk; there is no account and no hosted service.

The README's tool reference is headed 74 tools, yet a client sees far fewer. Unless TOKEN_OPTIMIZER_TOOL_PROFILE picks another profile, the server advertises a core set of 19 tools and turns away calls to anything else by name (src/server/tool-profile.ts). That includes cache_warmup, smart_cache and clear_cache, which the README's own troubleshooting steps tell you to call. Those only work with the profile set to full, which the README says brings 104 tools and roughly 30,000 tokens of schemas, against about 4,800 for core.

The server alone only offers tools the model may ignore. The makers recommend their Claude Code plugin or the hooks that the separate token-optimizer-install command writes, which deny built-in reads, greps and edits and point the agent to the cached tools.

What it needs

Runs through npx; any MCP client that speaks stdio. Enforcing hooks are a separate step: npm install -g @ooples/token-optimizer-mcp@latest and then token-optimizer-install, or the Claude Code plugin via /plugin marketplace add ooples/token-optimizer-mcp. Model calls through OrcaRouter need an OrcaRouter key or account.

Limits

• Limit Under the default core profile only 19 tools are offered and any other tool name is refused. Set TOKEN_OPTIMIZER_TOOL_PROFILE=full for the rest.
• Limit An unrecognised TOKEN_OPTIMIZER_TOOL_PROFILE value stops the server at start.
• Not covered The README's troubleshooting steps use cache_warmup, smart_cache and clear_cache, none of which the default core profile serves.
• Size cap The full profile costs about 30,000 tokens of tool schemas at startup, against about 4,800 for core.
• Size cap Its own notes say text under about 500 characters gains little from caching.
• Limit Cached entries are cleaned up after 7 days, per its README.
• Limit Token counts use a GPT-4 tokenizer, so figures for Claude models are estimates.
• Not covered Without the plugin or the hooks from token-optimizer-install, the model can keep using its built-in file tools.

Under the default core profile only 19 tools are offered and any other tool name is refused; set TOKEN_OPTIMIZER_TOOL_PROFILE=full for the rest, at a much larger schema cost. An unknown profile value stops the server at start. Its own pages say small text (under about 500 characters) and one-off content gain nothing, cached entries are cleaned up after 7 days, and the core token counting uses a GPT-4 tokenizer, so counts for Claude are an approximation. Without the plugin or hooks the model is free to keep using its built-in tools.

Who it suits

It suits developers who run long sessions in Claude Code, Codex, Gemini CLI, Copilot CLI or OpenCode and want fewer tokens spent on re-reading files and logs, with numbers to show the saving, all kept on their own machine. It is most useful with its hooks installed; as a bare MCP server it is advisory. Those who only want plain file access with no cache, no hooks editing client settings, and no local analytics database are better served by a simpler file server. It is a community project, not from any AI vendor.