token-compressor — Claude Code MCP server: install and use
Shortens prompts by 40–60% using local models and guards against semantic drift with vector similarity checks before sending text to LLMs.
claude mcp add token-compressor -- uvx token-compressor-mcpWhat token-compressor does
The server cuts prompt token size through a two-step local workflow. First, a local model cleans out conversational padding and redundancy while keeping negations and conditional clauses intact.
Next, an embedding check computes cosine similarity between the draft and the source text. If the score falls below the 0.85 threshold, the pipeline discards the rewrite and returns original text unchanged. Requests under 80 tokens bypass the process entirely.
Without a local Ollama daemon hosting llama3.2:1b and nomic-embed-text, every tool execution will fail. The package also requires Python 3.10+ alongside numpy and ollama.
What it helps with
- cut LLM prompt token consumption
- strip wordy boilerplate from system prompts
- keep conditional rules intact during prompt rewrites
- prevent semantic drift using embedding score checks
Example prompts for the agent
- Run
compress_prompton this draft instruction and check the token count - Shorten this long workflow context via token-compressor before submitting
How to install token-compressor
Platform CLI
claude mcp add token-compressor -- uvx token-compressor-mcpuvx runs the command named after the package; if the README names another one, use uvx --from token-compressor-mcp <command>
Platform CLI
codex mcp add token-compressor -- uvx token-compressor-mcpuvx runs the command named after the package; if the README names another one, use uvx --from token-compressor-mcp <command>
Config file
{
"mcpServers": {
"token-compressor": {
"command": "uvx",
"args": [
"token-compressor-mcp"
]
}
}
}uvx runs the command named after the package; if the README names another one, use uvx --from token-compressor-mcp <command>
Config file
{
"servers": {
"token-compressor": {
"type": "stdio",
"command": "uvx",
"args": [
"token-compressor-mcp"
]
}
}
}uvx runs the command named after the package; if the README names another one, use uvx --from token-compressor-mcp <command>
Platform CLI
gemini mcp add token-compressor uvx token-compressor-mcpuvx runs the command named after the package; if the README names another one, use uvx --from token-compressor-mcp <command>
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-compressor
How do I install token-compressor in Claude Code?
Run claude mcp add token-compressor -- uvx token-compressor-mcp. Make sure to pull llama3.2:1b and nomic-embed-text in Ollama beforehand.
What does token-compressor do?
It rewrites prompts using a compact local model to cut size by 40–60%, falling back to original phrasing if vector similarity drops under 0.85.
What prerequisites are required?
You need Python 3.10+, an active Ollama instance, and the llama3.2:1b and nomic-embed-text models. The Python environment must also have ollama and numpy installed.
