compresh-mcp is the Compresh MCP server. It exposes a compress tool over stdio, so any MCP-aware client (Claude Code, Claude Desktop, Cursor, OpenClaw, and others) can compress its conversation context before each model call. The free tier runs the open-source tulbase core locally; a Compresh API key unlocks the paid server-side memory layer (TUL 2.0, query-aware retrieval).
Install TESTED
Install with pipx — plain pip install fails on Homebrew/Debian system Python with PEP 668 "externally-managed-environment":
pipx install compresh-mcp
# verify it's on PATH:
which compresh-mcpRequires Python 3.10+. The server speaks MCP over stdio — you don't run it directly; your MCP client launches it.
Get an API key
A key is optional — without one, compresh-mcp compresses locally with the open-source tulbase core, free, and nothing leaves your machine. A key unlocks the server-side TUL 2.0 layer on paid models. Sign in with compresh-mcp login --google (or --github), or create an account — every new verified account gets $30 in free credit.
Free local mode is the default, not a limitation screen. The savings-share only applies once you opt into the paid TUL 2.0 layer — and new accounts start with a 5-day TUL 2.0 trial plus $30 credit on verification.
Configure your MCP client
Add compresh-mcp to your client's MCP server list and pass the key via env:
{
"mcpServers": {
"compresh": {
"command": "compresh-mcp",
"env": { "COMPRESH_API_KEY": "sk-comp_..." }
}
}
}
The exact file differs per client — see the per-host guides:
Claude Code,
Claude Desktop,
Cursor, and
OpenClaw.
Claude Code users: don't write a config file by hand —
current versions only read servers registered via
claude mcp add compresh --scope user -- "$(which compresh-mcp)"
(a hand-written ~/.claude/mcp.json is silently ignored and
/mcp reports "No MCP servers configured").
Optional environment variables
| Variable | Default | Notes |
|---|---|---|
COMPRESH_API_KEY | — | Your key (sk-comp_…). Optional — unlocks TUL 2.0; without it compression is free local tulbase. |
COMPRESH_API_BASE | https://api.compre.sh | Override the server base URL (staging/dev only). |
COMPRESH_NO_BROWSER | false | Set true to suppress the auto-opened signup page on headless/remote machines. |
Free vs paid
The free tier compresses locally with tulbase (open-source, MIT) — no data leaves your machine for compression. The paid TUL 2.0 enhancement runs server-side (api.compre.sh/v1/tul2, query-aware retrieval) on a savings-share rate (Starter 30%, Pro Quarterly 20%, Pro Semi-Annual 16%, Pro Annual 12%). New signups get $30 free credit. Full breakdown on the pricing page.
Verify
Start your client and run a conversation past a few turns. compresh-mcp logs each compression to stderr:
# expected stderr lines (one per compress call):
# [compresh] compress applied tier=free saving=...chars
# [compresh] compress applied tier=tul2 saving=...charsIf you instead see a welcome / signup screen, the key never reached the server — see Troubleshooting.
Troubleshooting
It shows an onboarding screen instead of compressing
COMPRESH_API_KEY wasn't passed to the subprocess. Confirm the key is in your client's mcpServers.compresh.env block (not just your shell), then fully restart the client so it relaunches the server.
The browser keeps opening to the signup page
That's the no-key onboarding flow. Once a valid key is set it won't fire again. On headless machines, set COMPRESH_NO_BROWSER=true.