MCP Compressor MCP Server

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/

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

• 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
• Universal Compatibility: Works with any MCP server (stdio, HTTP, SSE)
• Zero Functionality Loss: All tools remain fully accessible through the wrapper interface
• Easy Integration: Drop-in replacement for existing MCP servers

Installation

Install using pip or uv:

pip install mcp-compressor
# or
uv pip install mcp-compressor

Quick Start

Basic Usage

Wrap any MCP server by providing its command or URL:

# Wrap a stdio MCP server
uvx mcp-compressor uvx mcp-server-fetch

# Wrap a remote HTTP MCP server
uvx mcp-compressor https://example.com/server/mcp

# Wrap a remote SSE MCP server
uvx mcp-compressor https://example.com/server/sse

See uvx mcp-compressor --help for detailed documentation on available arguments.

Compression Levels

Control how much compression to apply with the --compression-level or -c flag:

# Low
mcp-compressor uvx mcp-server-fetch -c low

# Medium (default)
mcp-compressor uvx mcp-server-fetch -c medium

# High
mcp-compressor uvx mcp-server-fetch -c high

# Max
mcp-compressor uvx mcp-server-fetch -c max

Advanced Options

Stdio Servers

# Set working directory
mcp-compressor uvx mcp-server-fetch --cwd /path/to/dir

# Pass environment variables (supports environment variable expansion)
mcp-compressor uvx mcp-server-fetch \
  -e API_KEY=${MY_API_KEY} \
  -e DEBUG=true

Remote Servers (HTTP/SSE)

# Add custom headers
mcp-compressor https://api.example.com/mcp \
  -H "Authorization=Bearer ${TOKEN}" \
  -H "X-Custom-Header=value"

# Set timeout (default: 10 seconds)
mcp-compressor https://api.example.com/mcp \
  --timeout 30

Custom Server Names

When running multiple MCP servers through mcp-compressor, you can add custom prefixes to the wrapper tool names to avoid conflicts:

# Without server name - tools will be: get_tool_schema, invoke_tool
mcp-compressor uvx mcp-server-fetch

# With server name - tools will be: github_get_tool_schema, github_invoke_tool
mcp-compressor https://api.githubcopilot.com/mcp/ --server-name github

# Special characters are automatically sanitized
mcp-compressor uvx mcp-server-fetch --server-name "My Server!"
  # Results in: my_server__get_tool_schema, my_server__invoke_tool

Logging

# Set log level
mcp-compressor uvx mcp-server-fetch --log-level debug
mcp-compressor uvx mcp-server-fetch -l warning

Ho