slimctx MCP server
✓ VerifiedCompresses AI agent context like logs, JSON, and code to reduce token usage while allowing byte-exact retrieval of original content.
Also known as omkar9854/token_optimizer, token-optimizer, slimctx
- Stars
- 1
- Tools
- —
- Downloads, 30 days
- 66
- Latest version
- 0.1.0
- Last commit
- Jul 19, 2026
- License
- Apache-2.0
What is slimctx MCP?
slimctx compresses AI agent context like logs, JSON, and code to reduce token usage while allowing byte-exact retrieval of original content.
Summary generated from the project's README
About slimctx MCP server
Reducing token consumption for AI agents while maintaining data integrity is what slimctx achieves. This tool compresses various types of context, including logs, JSON, source code, and prose, before they are sent to a large language model. It is designed for developers and teams needing to manage high-volume data like SRE incident logs or large codebases without losing critical information.
Users can run this as a local MCP server by executing a Python command with a specified SQLite database path. The system is built using only the Python standard library, meaning it requires no external ML models, no network calls, and no heavy dependencies. This makes it suitable for air-gapped or highly secure environments.
Unlike other compression methods, every transformation is fully reversible. The server uses a content-addressed store to ensure that the original, byte-exact content can be retrieved at any time using a retrieval tool. It specifically protects important data by ensuring errors, warnings, and query-relevant code bodies are never dropped during the compression process.
What you can do with it
- 1Compressing massive SRE incident logsAn agent can process huge log files by collapsing repeated patterns into templates while keeping error lines verbatim.
- 2Retrieving original source dataWhen the model needs the full uncompressed text, it can call a tool to fetch the byte-exact original from the store.
Written from the project's README. Every use case is checked against a quote from it.
How to install slimctx MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall slimctx MCP in Claude Code
$ claude mcp add token-optimizer -- uvx slimctxInstall slimctx MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"token-optimizer": {
"command": "uvx",
"args": [
"slimctx"
]
}
}
}Install slimctx MCP in VS Code
.vscode/mcp.json
{
"servers": {
"token-optimizer": {
"type": "stdio",
"command": "uvx",
"args": [
"slimctx"
]
}
}
}Install slimctx MCP in VS Code CLI
$ code --add-mcp '{"name":"token-optimizer","type":"stdio","command":"uvx","args":["slimctx"]}'Install slimctx MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"token-optimizer": {
"command": "uvx",
"args": [
"slimctx"
]
}
}
}Install slimctx MCP in Codex
$ codex mcp add token-optimizer -- uvx slimctxInstall slimctx MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.token-optimizer] command = "uvx" args = ["slimctx"]
Install slimctx MCP in Gemini CLI
$ gemini mcp add -s user token-optimizer uvx -- slimctxInstall slimctx MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"token-optimizer": {
"command": "uvx",
"args": [
"slimctx"
]
}
}
}Automated checks
Ran Nov 15, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachableomkar9854/token_optimizer is public and reachablegithub.com/omkar9854/token_optimizer ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Sigstore attestation for slimctxpypi.org/project/slimctx/ ↗Pass
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-07-19github.com/omkar9854/token_optimizer ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from slimctxPass
- No critical advisory in the package or its dependencies1 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubslimctx — the token optimizer for AI agents
Zero-dependency, fully-reversible context compression for AI agents.
slimctx compresses what your agent reads — tool outputs, logs, JSON, source files, prose — before it reaches the LLM. Same answers, fraction of the tokens. Pure Python stdlib: no ML models, no downloads, no network calls, ever. Auditable end to end in ~1,600 lines.
from slimctx import Pipeline, Config
pipe = Pipeline(Config(target_tokens=32_000))
result = pipe.compress(messages) # OpenAI/Anthropic-style dicts
print(result.savings_ratio) # e.g. 0.82
original = pipe.retrieve("a1b2c3d4...") # byte-exact original, any time
Results (synthetic workloads modeled on real agent traffic)
| Workload | Before | After | Savings | Key facts kept |
|---|---|---|---|---|
| Code search (100 results) | 5,557 | 916 | 84% | ✓ |
| SRE incident debugging | 61,699 | 298 | 100% | ✓ |
| GitHub issue triage | 12,836 | 975 | 92% | ✓ |
| Codebase exploration | 5,734 | 2,760 | 52% | ✓ |
Every run also verifies that each planted "needle" (the FIXME, the OOMKill,
the outlier) survives compression, and that every lossy transform is
byte-exact reversible. Reproduce with python3 benchmarks/bench.py.
How it works
messages ──► ContentRouter ──► one of:
├─ JSON : lossless tabularization (repeated keys → header,
│ constant columns → legend), then relevance-ranked
│ row selection only if still over budget
├─ LOG : Drain-style template mining — repeated lines
│ collapse to `pattern [x1432]`; errors verbatim
├─ CODE : AST skeleton — signatures + docstrings kept,
│ bodies elided EXCEPT those relevant to the query
└─ TEXT : extractive sentence selection (BM25 + salience
+ position), verbatim, never paraphrased
The four guarantees
- Universal reversibility. Before any lossy transform, the original
goes into a content-addressed store (memory / SQLite / bring-your-own
cipher) and the output carries a
[slimctx-ref <hash> ...]marker. The model — or you — can always get the byte-exact original back. - Errors are never dropped. Every compressor pins error/warning content: log errors pass verbatim, salient JSON rows are kept, salient sentences outrank filler.
- Deterministic output. Same input → byte-identical output, across runs and processes. Compressed prefixes stay stable, so provider prompt-caches (Anthropic/OpenAI) keep hitting.
- Net gain or no-op. If a transform doesn't save enough tokens to pay for its marker, the original is kept untouched. The live zone (system prompt + last N messages) is never modified at all.
Why not just use Headroom?
Headroom is the established project in this space and is more featureful today (provider proxy with SSE streaming, agent wrappers, cross-agent memory, an ML compression model). slimctx makes a different set of trade-offs, aimed at locked-down / client-site deployments:
| Headroom | slimctx | |
|---|---|---|
| Reversibility | JSON only (CCR); dropped text is gone | every lossy transform |
| Log handling | generic text scoring | template mining ([x1432] collapse) |
| Code handling | AST skeleton | AST skeleton + query-relevant bodies kept |
| Dependencies | Rust core, ONNX runtime, 261MB HF model | stdlib only |
| Network egress | HuggingFace pull on first run | none, ever |
| Store encryption | none (plaintext SQLite) | cipher hook (bring your own) |
| Determinism | cache-aligner component | by construction (pure functions + memo) |
| Audit surface | ~10s of KLOC across 3 languages | ~1,200 lines of Python |
If you need the proxy/wrap ecosystem, use Headroom. If you need something you can read in an afternoon, run air-gapped, and certify for a client environment, use slimctx.
Install / test
pip install slimctx # from PyPI — or vendor the slimctx/ directory
python -m pytest tests/ -q # 26 tests: invariants, not examples
python3 benchmarks/bench.py # reproduce the numbers above
Integration sketches
As a library (any framework): call pipe.compress(messages) right
before your provider SDK call; expose pipe.retrieve as a tool named
retrieve so the model can pull originals.
As an MCP server (GitHub Copilot, Claude Code, Cursor, ...): ships built in, stdlib-only:
python3 -m slimctx.mcp_server --db ~/.slimctx/store.db
See USAGE.md for the GitHub Copilot (.vscode/mcp.json) setup
and a security deployment checklist.
Encrypted store:
from cryptography.fernet import Fernet # optional, your choice
f = Fernet(key)
store = SqliteStore("ccr.db", cipher=(f.encrypt, f.decrypt))
pipe = Pipeline(store=store)
License
Apache-2.0. Original implementation — no code derived from Headroom.
slimctx MCP questions
How do I add slimctx MCP to Claude Code?
Run claude mcp add token-optimizer -- uvx slimctx in your terminal. Add --scope user to make it available in every project.
How do I add slimctx MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
Is the compression reversible?
Yes, every lossy transform is byte-exact reversible, allowing the original content to be retrieved at any time.
Does it require external dependencies or network calls?
No, it is a zero-dependency tool built with the Python standard library that requires no downloads or network calls.