mcp-compressor

An MCP server wrapper for reducing tokens consumed by MCP tools.

• Github repository: https://github.com/atlassian-labs/mcp-compressor/
• Documentation https://atlassian-labs.github.io/mcp-compressor/
• TypeScript docs (GH Pages): https://atlassian-labs.github.io/mcp-compressor/typescript/
• TypeScript package code: https://github.com/atlassian-labs/mcp-compressor/blob/main/typescript/
• Blog https://www.atlassian.com/blog/developer/mcp-compression-preventing-tool-bloat-in-ai-agents/

📋 What's New

2026-04-06 — TypeScript Implementation

Added a sibling TypeScript implementation with matching compression concepts, OAuth support, in-process runtime APIs, and TypeScript CLI mode.

2026-04-06 — Single-Server MCP Config JSON Strings

COMMAND_OR_URL can now be a single MCP config JSON string. For now, mcpServers must contain exactly one server, and its key becomes the default --server-name unless one is passed explicitly.

2026-03-24 — CLI Mode

--cli-mode — Converts any wrapped MCP server into a local CLI. Generates an executable shell script (Unix) or .cmd file (Windows) so agents and users can interact with the backend via familiar command-line conventions rather than structured tool calls.

2026-03-24 — TOON Output

--toonify — Automatically converts JSON responses from wrapped backend tools into TOON format, a compact human- and LLM-readable alternative to JSON.

Overview

MCP Compressor is a proxy server that wraps existing Model Context Protocol (MCP) servers and compresses their tool descriptions to significantly reduce token consumption. Instead of exposing all tools with full schemas directly to language models, it provides a two-step interface:

1. get_tool_schema(tool_name) - Retrieve the full schema for a specific tool when needed
2. invoke_tool(tool_name, tool_input) - Execute a tool with the provided arguments

This approach dramatically reduces the number of tokens sent in the initial context while maintaining full functionality.

Why?

MCP servers are exploding in popularity, but their tool descriptions consume significant tokens in every LLM request. For example:

• The official GitHub MCP server exposes 94 tools consuming 17,600 tokens
• The official Atlassian MCP server consumes ~10,000 tokens

With 30k+ tokens just for tool descriptions, costs can reach 1-10 cents per request depending on prompt caching. MCP Compressor solves this by replacing dozens of tools with just 2 wrapper tools, achieving 70-97% token reduction while maintaining full functionality. This enables:

• Adding many MCP servers without blowing out context windows
• Significant cost savings on token-based API pricing
• Support for providing 100s or 1000s of tools across multiple servers to your agent

Features

• Python + TypeScript implementations: A mature Python implementation plus a sibling TypeScript package for Node.js consumers
• Token Reduction: Compress tool descriptions by up to 99% depending on compression level and tool count
• Multiple Compression Levels: Choose between low, medium, high, or max

... View full README on GitHub