compresh-mcp

MCP server for Compresh — production-grade context compression for LLM agent conversations.

Compresh adds query-aware retrieval (TUL 2.0) on top of the open-source tulbase compression core. Instead of summarizing older turns, it retrieves the turns relevant to the current question — lossless and role-tagged — from the full conversation history. This is the paid tier distribution, and it works free without an account (local tulbase compression).

Architecture (0.3.0+)

• Local: bundled tulbase (MIT, vendored as compresh_mcp.tulbase) runs on every turn for fast compression + cold-storage support (fetch_compressed / list_compressed MCP tools). Works with no API key and no account — fully local, free.

• Server: the TUL 2.0 paid layer (query-aware retrieval over full history, role-preserving render) runs on Compresh infrastructure via the /v1/tul2 endpoint, gated by your Compresh API key + tier.

• Degraded mode: if /v1/tul2 is unreachable (or your trial/credit runs out), compresh-mcp transparently falls back to the local tulbase result so compression never blocks.

The paid endpoint was the legacy /v1/tul1 through 0.2.x; 0.3.0 calls the canonical /v1/tul2 (the TUL 1.0 Q-matrix layer was retired in the 15 Jun 2026 retrieval pivot). The server keeps /v1/tul1 as a deprecated alias, so older clients keep working. Previously (0.1.0, yanked), paid classifiers shipped inside the client package and leaked paid features locally — install 0.3.0 or later. See CHANGELOG.md.

Related MCP server: PromptThrift MCP

What's the difference vs tulbase-mcp?

Both ship the same open-source compression core (cleanup, TurnBox, modality elision to cold storage, Protection Zone, LexRank summarization). tulbase-mcp is currently GitHub-only (not yet on PyPI). The difference is what happens on top of the shared core:

Why retrieval instead of summarization? Summaries are lossy by construction. In our T-bench (976-probe episodic benchmark, run registry published), TUL 2.0 retrieval matched or beat sending the full raw history while using ~99% fewer input tokens on long conversations — and on weaker models it improved answer quality by up to +22 points, where raw history either diluted the answer or simply didn't fit the context window.

Pricing

• 5-day free TUL 2.0 trial on every new account (no card, no commitment). When it ends, you fall back to free local tulbase — compression never stops.

• $30 free credit for every verified account: verify your email, or sign in with GitHub (provider-verified — instant). $30 = we waive our savings-share up to $30; it is not cash and no card is required.

• $10 minimum top-up, charged $7.50 with a permanent 25% top-up discount.

Saving-share is the cut Compresh takes on the savings measured against the user's chosen model. The base value comes from the actual model price (when known) or the provider family's cheapest model; anonymous / free-model usage falls back to a flat $0.20 / 1M saved input tokens.

Running a local / self-hosted model? Mark it in Settings (compre.sh/portal) — local models are free, so your savings-share stays $0.

See compre.sh/pricing for the canonical pricing page.

Installation

pipx install compresh-mcp     # recommended — isolated, works out of the box

(No pipx? brew install pipx on macOS. Plain pip install compresh-mcp works inside a virtualenv, but on Homebrew/Debian system Python it hits PEP 668 "externally-managed-environment" — pipx is the painless path.)

No account needed to start — on first run compresh-mcp compresses locally with the free tulbase core and prints a one-time note about the upgrade path.

To unlock TUL 2.0:

compresh-mcp signup you@example.com   # email-only signup — starts your 5-day trial
compresh-mcp login --github           # or sign in with GitHub (instant $30, no email verify)

Both write your key to ~/.compresh/apikey, where the server picks it up automatically. You can also set COMPRESH_API_KEY explicitly.

MCP client configuration

Claude Code

Register via the CLI — current Claude Code does not read a hand-written ~/.claude/mcp.json:

claude mcp add compresh --scope user \
  --env COMPRESH_API_BASE=https://api.compre.sh \
  -- "$(which compresh-mcp)"

(The server name goes right after add — placing it after the flags fails with missing required argument 'commandOrUrl'.)

If you sign in via compresh-mcp login / signup, your key lands in ~/.compresh/apikey and the server picks it up automatically — nothing to re-run. To pin an explicit key instead, re-run with --env COMPRESH_API_KEY=sk-comp_... appended (the entry is overwritten in place; omit the key to stay in free local mode). Then start a new claude session and check with /mcp — or claude mcp list from the shell.

"$(which compresh-mcp)" bakes in the full binary path — MCP hosts don't always inherit your shell PATH.

Cursor (~/.cursor/mcp.json)

{
  "mcpServers": {
    "compresh": {
      "command": "compresh-mcp",
      "env": {
        "COMPRESH_API_KEY": "sk-comp_...",
        "COMPRESH_API_BASE": "https://api.compre.sh"
      }
    }
  }
}

(Omit COMPRESH_API_KEY to run in free local mode. If Cursor can't find the binary, use the full path from which compresh-mcp — typically ~/.local/bin/compresh-mcp.)

Cowork

Cowork → Settings → Tools → MCP servers → Add:

• Command: compresh-mcp

• Environment: COMPRESH_API_KEY=sk-comp_... (optional)

Tools exposed

Same four tools as tulbase-mcp, with enhanced behavior:

• compress — local tulbase compression on every turn (protection_mode="balanced"); on paid models with a valid key, upgraded server-side to TUL 2.0 query-aware retrieval

• fetch_compressed, list_compressed, stats — same interface

Plus paid-tier extras:

• usage — current cycle budget, free credit balance, savings metrics

License

Business Source License 1.1 — see LICENSE. Production use permitted with valid Compresh API key. License automatically converts to MIT after 4 years (Year 2030).

Patents

Q-protective sentence ranking + Protection Zone are covered by TR-TPMK patent application 2026/007305 (Compresh Ltd, May 2026). A valid Compresh subscription grants implementation license.

Status

v0.3.2 — active development. APIs may change before v1.0. Issues and pull requests welcome.

Links

• compre.sh — product site

• Documentation — full reference

• GitHub — source

• Issues — bug reports

• tulbase (open core, MIT) — standalone