mcp-compressor

Ein MCP-Server-Wrapper zur Reduzierung der von MCP-Tools verbrauchten Token.

• Github-Repository: https://github.com/atlassian-labs/mcp-compressor/

• Dokumentation: https://atlassian-labs.github.io/mcp-compressor/

• TypeScript-Dokumentation (GH Pages): https://atlassian-labs.github.io/mcp-compressor/typescript/

• TypeScript-Paketcode: 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/

📋 Was ist neu

06.04.2026 — TypeScript-Implementierung

Hinzufügung einer TypeScript-Implementierung mit entsprechenden Komprimierungskonzepten, OAuth-Unterstützung, In-Process-Runtime-APIs und TypeScript-CLI-Modus.

06.04.2026 — MCP-Konfigurations-JSON-Strings für einzelne Server

COMMAND_OR_URL kann jetzt ein einzelner MCP-Konfigurations-JSON-String sein. Derzeit muss mcpServers genau einen Server enthalten, dessen Schlüssel zum Standardwert für --server-name wird, sofern nicht explizit einer übergeben wird.

24.03.2026 — CLI-Modus

--cli-mode — Wandelt jeden umschlossenen MCP-Server in eine lokale CLI um. Erzeugt ein ausführbares Shell-Skript (Unix) oder eine .cmd-Datei (Windows), sodass Agenten und Benutzer über vertraute Befehlszeilenkonventionen statt über strukturierte Tool-Aufrufe mit dem Backend interagieren können.

24.03.2026 — TOON-Ausgabe

--toonify — Konvertiert JSON-Antworten von umschlossenen Backend-Tools automatisch in das TOON-Format, eine kompakte, für Menschen und LLMs lesbare Alternative zu JSON.

Übersicht

MCP Compressor ist ein Proxy-Server, der bestehende Model Context Protocol (MCP)-Server umschließt und deren Tool-Beschreibungen komprimiert, um den Token-Verbrauch erheblich zu senken. Anstatt alle Tools mit vollständigen Schemata direkt für Sprachmodelle offenzulegen, bietet er eine zweistufige Schnittstelle:

1. get_tool_schema(tool_name) - Abrufen des vollständigen Schemas für ein bestimmtes Tool bei Bedarf

2. invoke_tool(tool_name, tool_input) - Ausführen eines Tools mit den bereitgestellten Argumenten

Dieser Ansatz reduziert die Anzahl der im anfänglichen Kontext gesendeten Token drastisch, während die volle Funktionalität erhalten bleibt.

Warum?

MCP-Server erfreuen sich wachsender Beliebtheit, aber ihre Tool-Beschreibungen verbrauchen bei jeder LLM-Anfrage erhebliche Mengen an Token. Zum Beispiel:

• Der offizielle GitHub MCP-Server stellt 94 Tools bereit, die 17.600 Token verbrauchen

• Der offizielle Atlassian MCP-Server verbraucht ca. 10.000 Token

Mit über 30.000 Token allein für Tool-Beschreibungen können die Kosten je nach Prompt-Caching 1-10 Cent pro Anfrage erreichen. MCP Compressor löst dies, indem Dutzende von Tools durch nur 2 Wrapper-Tools ersetzt werden, was eine Token-Reduzierung von 70-97 % bei voller Funktionalität ermöglicht. Dies erlaubt:

• Das Hinzufügen vieler MCP-Server, ohne die Kontextfenster zu sprengen

• Erhebliche Kosteneinsparungen bei tokenbasierter API-Preisgestaltung

• Unterstützung für die Bereitstellung von hunderten oder tausenden Tools über mehrere Server hinweg für Ihren Agenten

Funktionen

• Python- und TypeScript-Implementierungen: Eine ausgereifte Python-Implementierung sowie ein ergänzendes TypeScript-Paket für Node.js-Nutzer

• Token-Reduzierung: Komprimierung von Tool-Beschreibungen um bis zu 99 %, abhängig von Komprimierungsgrad und Tool-Anzahl

• Mehrere Komprimierungsstufen: Wählen Sie zwischen low, medium, high oder max

• Universelle Kompatibilität: Funktioniert mit jedem MCP-Server (stdio, HTTP, SSE)

• TOON-Ausgabekonvertierung: Optionale Konvertierung von JSON-Backend-Tool-Ergebnissen in TOON mit --toonify

• CLI-Modus: Wandeln Sie jeden MCP-Server mit --cli-mode in eine lokale CLI um — generiert ein Shell-Skript, mit dem Sie (oder ein KI-Agent) über vertraute Befehlszeilensyntax mit dem Backend interagieren können

• Kein Funktionsverlust: Alle Tools bleiben über die Wrapper-Schnittstelle vollständig zugänglich

• Einfache Integration: Drop-in-Ersatz für bestehende MCP-Server

Python vs. TypeScript

Verwenden Sie die Python-Implementierung, wenn Sie heute den ausgereiftesten Funktionsumfang wünschen. Verwenden Sie die TypeScript-Implementierung, wenn Sie Node.js-native Nutzung, In-Process-Einbettung oder eine engere Integration in das TypeScript-Ökosystem benötigen.

Installation

Installieren Sie es mit pip oder uv:

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

Schnellstart

Grundlegende Verwendung

Umschließen Sie jeden MCP-Server, indem Sie dessen Befehl oder URL angeben:

# 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

Siehe uvx mcp-compressor --help für eine detaillierte Dokumentation der verfügbaren Argumente.

Komprimierungsstufen

Steuern Sie mit dem Flag --compression-level oder -c, wie stark die Komprimierung sein soll:

# 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

CLI-Modus

Wenn Sie möchten, dass sich das umschlossene Backend wie ein lokales Befehlszeilen-Tool verhält, beginnen Sie hier:

mcp-compressor --cli-mode --server-name atlassian -- https://mcp.atlassian.com/v1/mcp

Verwenden Sie dann das generierte CLI-Skript:

atlassian --help

Anstatt das umschlossene Backend als viele MCP-Tools offenzulegen, verwandelt --cli-mode das Backend in eine lokale CLI mit einem einzigen Hilfe-Tool zur Erkundung. Dies ist besonders nützlich, wenn ein Agent über eine Shell-ähnliche Schnittstelle arbeiten soll oder wenn ein Backend-Server bereits eher als Befehle und Flags denn als direkte MCP-Tool-Aufrufe sinnvoll ist.

flowchart LR
    Client["MCP Client / Agent"] -->|discovers| HelpTool["<server_name>_help"]
    HelpTool -->|explains commands| GeneratedCLI["Generated local CLI script\n(e.g. atlassian)"]
    User["User or Agent"] -->|runs CLI subcommands| GeneratedCLI
    GeneratedCLI --> Bridge["Local HTTP bridge\n127.0.0.1:<port>"]
    Bridge --> Compressor["mcp-compressor\n--cli-mode"]
    Compressor --> Backend["Wrapped MCP server"]
    Backend --> Compressor
    Compressor --> Bridge
    Bridge --> GeneratedCLI

Warum der CLI-Modus wichtig ist

• Ein Tool statt vieler: Der MCP-Client sieht ein einzelnes <server_name>_help-Tool anstelle des Wrapper-Toolsets

• Natürliche Shell-UX: Backend-Tools werden zu CLI-Unterbefehlen mit Flags, die aus dem JSON-Schema abgeleitet sind

• Gut geeignet für Agenten: Agenten können die Hilfe untersuchen und dann wiederholt einen lokalen Befehl aufrufen, ohne die gesamte MCP-Tool-Oberfläche im Kontext mitführen zu müssen

• OAuth funktioniert weiterhin: Wenn das umschlossene Backend OAuth erfordert, führt der CLI-Modus diesen Verbindungsablauf durch, bevor die lokale CLI generiert wird

• TOON standardmäßig: --toonify ist im CLI-Modus automatisch aktiviert für eine kompakte, lesbare Ausgabe

Schnellstart für den CLI-Modus

# Wrap a remote MCP server as a local CLI
uvx mcp-compressor --cli-mode --server-name atlassian -- https://mcp.atlassian.com/v1/mcp

# Or pass a single MCP config JSON string
uvx mcp-compressor --cli-mode '{"mcpServers": {"atlassian": {"url": "https://mcp.atlassian.com/v1/mcp"}}}'

Wenn der CLI-Modus startet, passiert Folgendes:

1. Verbindung zum umschlossenen Backend-Server, einschließlich OAuth, falls erforderlich

2. Start einer lokalen HTTP-Brücke auf 127.0.0.1:<port>

3. Generierung eines ausführbaren Skripts — unter Unix wird dies normalerweise nach ~/.local/bin/<name> geschrieben, falls im PATH verfügbar, andernfalls in das aktuelle Verzeichnis; unter Windows wird ein .cmd-Launcher in ein geeignetes Verzeichnis im PATH geschrieben

4. Bereitstellung eines einzelnen MCP-Tools namens <server_name>_help, damit der Client die generierte CLI und ihre Unterbefehle entdecken kann

Beispiel für die Verwendung nach dem Start:

# Top-level help — lists all subcommands
atlassian --help

# Per-tool help — shows flags derived from the backend tool schema
atlassian get-confluence-page --help

# Invoke a tool using ordinary CLI flags
atlassian get-confluence-page --cloud-id abc123 --page-id 456

# Escape hatch for complex inputs
atlassian create-jira-issue --json '{"cloudId":"abc","projectKey":"PROJ","summary":"Bug"}'

Die Namen der CLI-Unterbefehle sind die snake_case → kebab-case-Konvertierung der Backend-Tool-Namen (z. B. getConfluencePage → get-confluence-page). Das generierte Skript funktioniert nur, während mcp-compressor --cli-mode läuft. Verwenden Sie --cli-port, wenn Sie die lokale Brücke an einen bestimmten Port binden möchten.

Erweiterte Optionen

Stdio-Server

# 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-Server (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

Benutzerdefinierte Servernamen

Wenn Sie mehrere MCP-Server über mcp-compressor ausführen, können Sie den Wrapper-Tool-Namen benutzerdefinierte Präfixe hinzufügen, um Konflikte zu vermeiden:

# 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

TOON-Ausgabekonvertierung

Verwenden Sie --toonify, um JSON-Backend-Tool-Ergebnisse automatisch in das TOON-Format zu konvertieren.

# Convert JSON backend tool results to TOON
mcp-compressor https://api.example.com/mcp --toonify

Wenn --toonify aktiviert ist:

• Erfolgreiche Backend-Tool-Ergebnisse, die durch direkte Tool-Aufrufe zurückgegeben werden, werden in TOON umgewandelt, wenn es sich um JSON-Objekte oder -Arrays handelt

• Erfolgreiche Backend-Tool-Ergebnisse, die durch invoke_tool(...) zurückgegeben werden, werden ebenfalls in TOON umgewandelt

• Wrapper-Antworten von get_tool_schema(...) und list_tools(...) werden niemals in TOON umgewandelt

• Von Wrappern generierte Anleitungen oder Fehlermeldungen von invoke_tool(...) werden niemals in TOON umgewandelt

• Nicht-JSON-Text wird unverändert zurückgegeben

CLI-Modus

Der CLI-Modus ist im oben genannten Abschnitt CLI-Modus dokumentiert. Kurzfassung: Verwenden Sie --cli-mode, geben Sie dem Server einen Namen und interagieren Sie mit dem generierten lokalen Skript, während mcp-compressor läuft.

mcp-compressor https://mcp.atlassian.com/v1/mcp --server-name atlassian --cli-mode --cli-port 8765

Protokollierung

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

Funktionsweise

Der MCP Compressor fungiert als transparenter Proxy zwischen Ihrem LLM-Client und dem zugrunde liegenden MCP-Server:

flowchart TB
    subgraph github["GitHub MCP"]
        g1["create_pr"]
        g2["get_me"]
        g3["list_repos"]
        g4["get_issue"]
        g5["..."]
        g6["(+87 more tools)"]
    end

    subgraph proxy["MCP Compressor"]
        t1["get_tool_schema"]
        t2["invoke_tool"]
    end

    subgraph client["MCP Client"]
    end

    g1 <--> proxy
    g2 <--> proxy
    g3 <--> proxy
    g4 <--> proxy
    g6 <--> proxy
    t1 <--> client
    t2 <--> client

Anstatt alle Tools mit vollständigen Schemata zu sehen (die oft tausende von Token umfassen), sieht das LLM nur:

Available tools:
<tool>search_web(query, max_results): Search the web for information</tool>
<tool>get_weather(location, units): Get current weather for a location</tool>
<tool>send_email(to, subject, body): Send an email message</tool>

Wenn das LLM ein Tool verwenden muss, ruft es zuerst get_tool_schema(tool_name) auf, um das vollständige Schema abzurufen, und dann invoke_tool(tool_name, tool_input), um es auszuführen.

Wenn --toonify aktiviert ist, werden erfolgreiche Backend-Tool-Ergebnisse von JSON in TOON konvertiert, bevor sie an den Client zurückgegeben werden. Die Wrapper-Hilfsantworten selbst werden nicht neu formatiert.

Im CLI-Modus (--cli-mode) stellt der Compressor ein einzelnes <server_name>_help-Tool anstelle der üblichen Wrapper bereit. Die gesamte tatsächliche Tool-Interaktion erfolgt über das generierte Shell-Skript mittels einer lokalen HTTP-Brücke.

sequenceDiagram
    participant Client as MCP Client
    participant Compressor as MCP Compressor
    participant Server as GitHub MCP<br/>(91 tools)

    Client->>Compressor: list_tools()
    Compressor->>Server: list_tools()
    Server-->>Compressor: create_pr, get_me, list_repos, ...
    Compressor-->>Client: get_tool_schema, invoke_tool

    Client->>Compressor: get_tool_schema("create_pr")
    Compressor-->>Client: create_pr description & schema

    Client->>Compressor: invoke_tool("create_pr", {...})
    Compressor->>Server: create_pr({...})
    Server-->>Compressor: result
    Compressor-->>Client: result

Details zu den Komprimierungsstufen

Die beste Wahl der Komprimierungsstufe hängt von einer Reihe von Faktoren ab, darunter:

1. Die Anzahl der Tools im MCP-Server - je mehr Tools, desto mehr Komprimierung verwenden.

2. Wie häufig die Tools voraussichtlich verwendet werden - wenn Tools von einem komprimierten Server selten verwendet werden, komprimieren Sie sie stärker, um zu verhindern, dass Token unnötig verbraucht werden.

3. Wie ungewöhnlich oder komplex die Tools sind - einfachere Tools können stärker komprimiert werden, ohne dass dies große Nachteile hat. Denken Sie an ein einfaches bash-Tool mit einem einzigen Eingabeargument command. Jedes moderne LLM wird genau verstehen, wie es zu verwenden ist, nachdem es nur den Tool-Namen und den Namen des Arguments gesehen hat. Sofern keine unerwartete interne Logik im Tool vorhanden ist, kann eine aggressive Komprimierung ohne große Nachteile angewendet werden.

Konfiguration mit MCP-JSON-Datei

Sie können auch einen MCP-Konfigurations-JSON-String für einen einzelnen Server direkt als COMMAND_OR_URL in der CLI übergeben. Dies ist besonders nützlich für Remote-Server, wenn die Konfiguration selbst die URL, Header, Transport- oder Stdio-Befehlsdetails enthalten soll.

Derzeit unterstützt die direkte JSON-String-Eingabe genau einen Servereintrag in mcpServers.

Um mcp-compressor in einer MCP-JSON-Konfigurationsdatei zu konfigurieren, verwenden Sie das folgende Muster:

GXP