token-optimizer-mcp — Claude Code MCP server: features and setup
This MCP server compresses request content and can move blocks it cannot compress into a file. It can help when logs, search results, or repeated reads fill an agent’s context.
claude mcp add --env TOKEN_OPTIMIZER_CACHE_DIR=<TOKEN_OPTIMIZER_CACHE_DIR> --transport stdio token-optimizer-mcp -- npx -y @ooples/token-optimizer-mcpWhat token-optimizer-mcp does
The server compresses blocks in a request without moving their contents. In proxy mode, it can also move a block that resists compression into a file and leave a marker with its path. The README compares these as separate modes against HeadRoom using test corpora.
In Claude Code, add the server with claude mcp add and run it through npx. To configure a cache directory, the command accepts TOKEN_OPTIMIZER_CACHE_DIR. Node.js 22 or newer is required. Without the proxy mode, blocks stay in the request and are handled through compression.
What it helps with
- compress long build logs before asking an agent to inspect them
- reduce repeated-read content in an agent request
- move an incompressible block to a file and keep its path
- shrink context containing search results
Example prompts for the agent
- Compress the build output before analyzing the errors.
- Process these code search results and trim unnecessary context.
- Move the large block that cannot be compressed into a file and keep its path.
How to install token-optimizer-mcp
Platform CLI
claude mcp add --env TOKEN_OPTIMIZER_CACHE_DIR=<TOKEN_OPTIMIZER_CACHE_DIR> --transport stdio token-optimizer-mcp -- npx -y @ooples/token-optimizer-mcpReplace <…> with your own values
Platform CLI
codex mcp add token-optimizer-mcp --env TOKEN_OPTIMIZER_CACHE_DIR=<TOKEN_OPTIMIZER_CACHE_DIR> -- npx -y @ooples/token-optimizer-mcpReplace <…> with your own values
Config file
{
"mcpServers": {
"token-optimizer-mcp": {
"command": "npx",
"args": [
"-y",
"@ooples/token-optimizer-mcp"
],
"env": {
"TOKEN_OPTIMIZER_CACHE_DIR": "<TOKEN_OPTIMIZER_CACHE_DIR>"
}
}
}
}Replace <…> with your own values
Config file
{
"servers": {
"token-optimizer-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@ooples/token-optimizer-mcp"
],
"env": {
"TOKEN_OPTIMIZER_CACHE_DIR": "<TOKEN_OPTIMIZER_CACHE_DIR>"
}
}
}
}Replace <…> with your own values
Platform CLI
gemini mcp add -e TOKEN_OPTIMIZER_CACHE_DIR=<TOKEN_OPTIMIZER_CACHE_DIR> token-optimizer-mcp npx -y @ooples/token-optimizer-mcpReplace <…> with your own values
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about token-optimizer-mcp
How do I install token-optimizer-mcp in Claude Code?
Run claude mcp add token-optimizer-mcp -- npx -y @ooples/token-optimizer-mcp. To set a cache directory, use claude mcp add --env TOKEN_OPTIMIZER_CACHE_DIR=<TOKEN_OPTIMIZER_CACHE_DIR> --transport stdio token-optimizer-mcp -- npx -y @ooples/token-optimizer-mcp. Node.js 22 or newer is required.
What does token-optimizer-mcp do?
It compresses blocks in agent requests. In proxy mode, it can move a block it cannot compress into a file and leave a marker pointing to it.
Which Node.js version does token-optimizer-mcp require?
It requires Node.js 22 or newer.
