Skip to content
Back to search

mcp-compressor

An MCP server wrapper for reducing tokens consumed by MCP tools, available in typescript, python, and rust

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/atlassian-labs/mcp-compressor with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/atlassian-labs/mcp-compressor'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/atlassian-labs--mcp-compressor/badge.svg)](/listings/atlassian-labs--mcp-compressor)

HTML

<a href="/listings/atlassian-labs--mcp-compressor"><img src="/api/listings/atlassian-labs--mcp-compressor/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 199 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # mcp-compressor
  2. [![MCP Toplist](https://mcptoplist.com/badge/glama%2Fatlassian-labs%2Fmcp-compressor.svg)](https://mcptoplist.com/server/glama%2Fatlassian-labs%2Fmcp-compressor)
  3. [![Release](https://img.shields.io/github/v/release/atlassian-labs/mcp-compressor)](https://github.com/atlassian-labs/mcp-compressor/releases)
  4. [![Build status](https://img.shields.io/github/actions/workflow/status/atlassian-labs/mcp-compressor/main.yml?branch=main)](https://github.com/atlassian-labs/mcp-compressor/actions/workflows/main.yml?query=branch%3Amain)
  5. [![Commit activity](https://img.shields.io/github/commit-activity/m/atlassian-labs/mcp-compressor)](https://github.com/atlassian-labs/mcp-compressor/commits/main)
  6. [![License](https://img.shields.io/github/license/atlassian-labs/mcp-compressor)](https://github.com/atlassian-labs/mcp-compressor/blob/main/LICENSE)
  7. `mcp-compressor` helps agents use large MCP servers without spending huge amounts of context on tool descriptions and schemas.
  8. It can run as a CLI MCP proxy, or be embedded directly from Python, TypeScript, or Rust.
  9. - **Documentation**: <https://atlassian-labs.github.io/mcp-compressor/>
  10. - **Repository**: <https://github.com/atlassian-labs/mcp-compressor/>
  11. - **Blog**: <https://www.atlassian.com/blog/developer/mcp-compression-preventing-tool-bloat-in-ai-agents/>
  12. ## Why mcp-compressor?
  13. A powerful MCP server can expose dozens or hundreds of tools. Each tool has a name, description, input schema, and sometimes large nested JSON Schema details. Sending all of that to a model up front can waste thousands of tokens before the agent has done any useful work.
  14. For example, large public MCP servers can spend thousands or tens of thousands of tokens on tool descriptions alone. That creates three problems:
  15. - models spend context on tools they may never call,
  16. - cost increases for every request that carries the tool list,
  17. - adding multiple MCP servers quickly overwhelms practical context budgets.
  18. `mcp-compressor` changes the interaction pattern: the model sees a small compressed surface first, asks for the full schema only for the selected tool, and then invokes that tool.
  19. Opt into bounded tool responses in any proxy mode with `--shrinkfit` (20,000
  20. characters) or `--shrinkfit=10000`. Object responses retain their top-level shape
  21. and add `truncation` instructions. CLI/Code/Just Bash sessions save the full
  22. original in a private temporary file; MCP callers can recall with `full=true`
  23. using a session cache or bypassing shrinking on a backend call. See
  24. [recoverable response shrinking](https://atlassian-labs.github.io/mcp-compressor/usage/shrinkfit/).
  25. ## Pattern 1: compressed MCP proxy
  26. Use this when you want any MCP client to see a smaller tool surface.
  27. ```mermaid
  28. sequenceDiagram
  29. participant Client as MCP client / agent
  30. participant Proxy as mcp-compressor
  31. participant Backend as Backend MCP server
  32. Client->>Proxy: tools/list
  33. Proxy->>Backend: tools/list
  34. Backend-->>Proxy: all backend tools and schemas
  35. Proxy-->>Client: compact wrapper tools
  36. Client->>Proxy: get_tool_schema(tool_name)
  37. Proxy-->>Client: full schema for selected tool
  38. Client->>Proxy: invoke_tool(tool_name, input)
  39. Proxy->>Backend: tools/call selected backend tool
  40. Backend-->>Proxy: tool result
  41. Proxy-->>Client: result
  42. ```
  43. The frontend usually exposes only:
  44. - `get_tool_schema`
  45. - `invoke_tool`
  46. - optionally `list_tools` at `max` compression
  47. ### MCP protocol negotiation
  48. The stdio and streamable HTTP frontends accept both legacy `initialize` clients
  49. and modern `2026-07-28` discovery clients, including Python MCP SDK 2.2.0 in
  50. `auto`, `legacy`, or explicit `2026-07-28` mode. Backend connections initialize
  51. independently, so modern clients can use legacy backends without sending
  52. frontend negotiation metadata to them. Backends must support legacy `initialize`;
  53. modern-only backends are not supported. Application tool-call metadata and tool
  54. result content, annotations, structured content, and error flags are preserved.
  55. Modern catalog and resource-read responses use `ttlMs: 0` and private cache
  56. scope. Catalogs remain static for the connection; dynamic change subscriptions
  57. are not advertised or supported. Legacy responses omit modern protocol fields.
  58. ## Pattern 2: local proxy for SDKs and generated clients
  59. Use this when your application wants to embed compression directly and call tools from code or shell commands.
  60. ```mermaid
  61. flowchart LR
  62. App[Python / TypeScript / Rust app]
  63. SDK[CompressorClient]
  64. Proxy[Local session proxy\n/token auth]
  65. Generated[Generated CLI / Python / TS clients]
  66. Backend[MCP backend servers]
  67. App --> SDK
  68. SDK --> Proxy
  69. Generated --> Proxy
  70. Proxy --> Backend
  71. ```
  72. The SDK starts a local session proxy for generated clients. Generated clients call that proxy using a session token. Your app does **not** need to spawn a `mcp-compressor` stdio subprocess.
  73. ## Features
  74. - [Compressed MCP proxy](https://atlassian-labs.github.io/mcp-compressor/usage/cli/#standard-mcp-proxy) for existing MCP clients.
  75. - [Compression levels](https://atlassian-labs.github.io/mcp-compressor/concepts/how-it-works/#compression-levels): `low`, `medium`, `high`, `max`.
  76. - [Python, TypeScript, and Rust SDKs](https://atlassian-labs.github.io/mcp-compressor/usage/sdks/) with aligned `CompressorClient` APIs.
  77. - [Local TypeScript tool compression](https://atlassian-labs.github.io/mcp-compressor/usage/sdks/#compress-local-typescript-tools) for AI SDK-style in-process tools.
  78. - [CLI Mode and Code Mode generated clients](https://atlassian-labs.github.io/mcp-compressor/usage/generated-clients/): shell commands plus Python/TypeScript functions.
  79. - [Just Bash integration](https://atlassian-labs.github.io/mcp-compressor/usage/just-bash/) for command-oriented agents.
  80. - [Remote streamable HTTP MCP backends](https://atlassian-labs.github.io/mcp-compressor/usage/auth-and-remote/).
  81. - [OAuth support](https://atlassian-labs.github.io/mcp-compressor/usage/auth-and-remote/#native-oauth) for providers that support browser authorization.
  82. - [Tool filters and TOON output](https://atlassian-labs.github.io/mcp-compressor/concepts/configuration/#filters) to further reduce context.
  83. - [Atlassian MCP example](https://atlassian-labs.github.io/mcp-compressor/examples/atlassian/) with OAuth-first usage.
  84. ## Quick example
  85. === "CLI"
  86. ```bash
  87. mcp-compressor -c medium -- python server.py
  88. ```
  89. === "Python"
  90. ```python
  91. from mcp_compressor import CompressorClient
  92. with CompressorClient(
  93. servers={"alpha": {"command": "python", "args": ["server.py"]}},
  94. compression_level="medium",
  95. ) as proxy:
  96. print([tool.name for tool in proxy.tools])
  97. print(proxy.invoke("echo", {"message": "hello"}))
  98. ```
  99. === "TypeScript"
  100. ```ts
  101. import { CompressorClient } from "@atlassian/mcp-compressor";
  102. const proxy = await new CompressorClient({
  103. servers: { alpha: { command: "python", args: ["server.py"] } },
  104. compressionLevel: "medium",
  105. }).connect();
  106. try {
  107. console.log(proxy.tools.map((tool) => tool.name));
  108. console.log(await proxy.invoke("echo", { message: "hello" }));
  109. } finally {
  110. proxy.close();
  111. }
  112. ```
  113. === "Rust"
  114. ```rust
  115. use mcp_compressor::compression::CompressionLevel;
  116. use mcp_compressor::sdk::{CompressorClient, ServerConfig};
  117. use serde_json::json;
  118. let proxy = CompressorClient::builder()
  119. .server("alpha", ServerConfig::command("python").arg("server.py"))
  120. .compression_level(CompressionLevel::Medium)
  121. .build()
  122. .connect()
  123. .await?;
  124. let result = proxy.invoke("echo", json!({ "message": "hello" })).await?;
  125. ```
  126. ## Generated clients
  127. **CLI Mode** generates shell commands:
  128. ```bash
  129. mcp-compressor --cli-mode --server-name atlassian -- https://mcp.atlassian.com/v1/mcp
  130. atlassian get-accessible-atlassian-resources
  131. ```
  132. **Code Mode** generates Python or TypeScript functions:
  133. ```python
  134. # generated-py/atlassian.py
  135. import atlassian
  136. resources = atlassian.get_accessible_atlassian_resources()
  137. ```
  138. ```ts
  139. import { getAccessibleAtlassianResources } from "./generated-ts/atlassian.ts";
  140. const resources = await getAccessibleAtlassianResources();
  141. ```
  142. See [Code Mode and generated clients](https://atlassian-labs.github.io/mcp-compressor/usage/generated-clients/) for more detail.
  143. ## Where to go next
  144. 1. [Install the package you need](https://atlassian-labs.github.io/mcp-compressor/getting-started/installation/).
  145. 2. Run the [quickstart](https://atlassian-labs.github.io/mcp-compressor/getting-started/quickstart/).
  146. 3. Read [how compression works](https://atlassian-labs.github.io/mcp-compressor/concepts/how-it-works/).
  147. 4. Choose between [CLI usage](https://atlassian-labs.github.io/mcp-compressor/usage/cli/), [SDK usage](https://atlassian-labs.github.io/mcp-compressor/usage/sdks/), [generated clients](https://atlassian-labs.github.io/mcp-compressor/usage/generated-clients/), and [Just Bash](https://atlassian-labs.github.io/mcp-compressor/usage/just-bash/).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.