mcp-compressor

Un envoltorio de servidor MCP para reducir los tokens consumidos por las herramientas MCP.

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

• Documentación: https://atlassian-labs.github.io/mcp-compressor/

• Documentación de TypeScript (GH Pages): https://atlassian-labs.github.io/mcp-compressor/typescript/

• Código del paquete TypeScript: 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/

📋 Novedades

06-04-2026 — Implementación en TypeScript

Se añadió una implementación hermana en TypeScript con conceptos de compresión coincidentes, soporte para OAuth, APIs de tiempo de ejecución en proceso y modo CLI de TypeScript.

06-04-2026 — Cadenas JSON de configuración MCP de servidor único

COMMAND_OR_URL ahora puede ser una cadena JSON de configuración MCP única. Por ahora, mcpServers debe contener exactamente un servidor, y su clave se convierte en el --server-name predeterminado a menos que se pase uno explícitamente.

24-03-2026 — Modo CLI

--cli-mode — Convierte cualquier servidor MCP envuelto en una CLI local. Genera un script de shell ejecutable (Unix) o un archivo .cmd (Windows) para que los agentes y usuarios puedan interactuar con el backend mediante convenciones de línea de comandos familiares en lugar de llamadas a herramientas estructuradas.

24-03-2026 — Salida TOON

--toonify — Convierte automáticamente las respuestas JSON de las herramientas de backend envueltas al formato TOON, una alternativa compacta al JSON legible tanto por humanos como por LLMs.

Descripción general

MCP Compressor es un servidor proxy que envuelve servidores del Protocolo de Contexto de Modelo (MCP) existentes y comprime las descripciones de sus herramientas para reducir significativamente el consumo de tokens. En lugar de exponer todas las herramientas con esquemas completos directamente a los modelos de lenguaje, proporciona una interfaz de dos pasos:

1. get_tool_schema(tool_name) - Recupera el esquema completo de una herramienta específica cuando sea necesario

2. invoke_tool(tool_name, tool_input) - Ejecuta una herramienta con los argumentos proporcionados

Este enfoque reduce drásticamente el número de tokens enviados en el contexto inicial mientras mantiene la funcionalidad completa.

¿Por qué?

Los servidores MCP están explotando en popularidad, pero las descripciones de sus herramientas consumen una cantidad significativa de tokens en cada solicitud de LLM. Por ejemplo:

• El servidor MCP oficial de GitHub expone 94 herramientas que consumen 17.600 tokens

• El servidor MCP oficial de Atlassian consume ~10.000 tokens

Con más de 30.000 tokens solo para las descripciones de las herramientas, los costes pueden alcanzar 1-10 centavos por solicitud dependiendo del almacenamiento en caché de las peticiones. MCP Compressor resuelve esto reemplazando docenas de herramientas con solo 2 herramientas envolventes, logrando una reducción de tokens del 70-97% mientras mantiene la funcionalidad completa. Esto permite:

• Añadir muchos servidores MCP sin agotar las ventanas de contexto

• Ahorros significativos en costes de precios de API basados en tokens

• Soporte para proporcionar cientos o miles de herramientas a través de múltiples servidores a su agente

Características

• Implementaciones en Python + TypeScript: Una implementación madura en Python más un paquete hermano en TypeScript para consumidores de Node.js

• Reducción de tokens: Comprime las descripciones de las herramientas hasta en un 99% dependiendo del nivel de compresión y el número de herramientas

• Múltiples niveles de compresión: Elija entre low, medium, high o max

• Compatibilidad universal: Funciona con cualquier servidor MCP (stdio, HTTP, SSE)

• Conversión de salida TOON: Opcionalmente, convierta los resultados de las herramientas de backend JSON a TOON con --toonify

• Modo CLI: Convierta cualquier servidor MCP en una CLI local con --cli-mode — genera un script de shell que le permite (o a un agente de IA) interactuar con el backend mediante una sintaxis de línea de comandos familiar

• Cero pérdida de funcionalidad: Todas las herramientas permanecen totalmente accesibles a través de la interfaz envolvente

• Integración sencilla: Reemplazo directo para servidores MCP existentes

Python vs TypeScript

Utilice la implementación de Python cuando desee el conjunto de características más maduro hoy en día. Utilice la implementación de TypeScript cuando desee un uso nativo de Node.js, incrustación en proceso o una integración más estrecha con el ecosistema de TypeScript.

Instalación

Instale usando pip o uv:

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

Inicio rápido

Uso básico

Envuelva cualquier servidor MCP proporcionando su comando o 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

Consulte uvx mcp-compressor --help para obtener documentación detallada sobre los argumentos disponibles.

Niveles de compresión

Controle cuánta compresión aplicar con la bandera --compression-level o -c:

# 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

Modo CLI

Si desea que el backend envuelto se comporte como una herramienta de línea de comandos local, comience aquí:

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

Luego use el script CLI generado:

atlassian --help

En lugar de exponer el backend envuelto como muchas herramientas MCP, --cli-mode convierte el backend en una CLI local con una única herramienta de ayuda para el descubrimiento. Esto es especialmente útil cuando desea que un agente trabaje a través de una interfaz de estilo shell, o cuando un servidor backend ya tiene más sentido como comandos y banderas que como llamadas directas a herramientas MCP.

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

Por qué es importante el modo CLI

• Una herramienta en lugar de muchas: el cliente MCP ve una única herramienta <server_name>_help en lugar del conjunto de herramientas envolventes

• UX de shell natural: las herramientas de backend se convierten en subcomandos CLI con banderas derivadas del esquema JSON

• Funciona bien para agentes: los agentes pueden inspeccionar la ayuda y luego llamar a un comando local repetidamente sin llevar toda la superficie de herramientas MCP en el contexto

• OAuth sigue funcionando: si el backend envuelto requiere OAuth, el modo CLI realiza ese flujo de conexión antes de generar la CLI local

• TOON por defecto: --toonify se habilita automáticamente en el modo CLI para una salida compacta y legible

Inicio rápido del modo CLI

# 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"}}}'

Cuando se inicia el modo CLI, este:

1. Se conecta al servidor backend envuelto, incluyendo OAuth si es necesario

2. Inicia un puente HTTP local en 127.0.0.1:<port>

3. Genera un script ejecutable — en Unix, esto generalmente se escribe en ~/.local/bin/<name> si está disponible en PATH, de lo contrario en el directorio actual; en Windows, escribe un lanzador .cmd en un directorio adecuado en PATH

4. Expone una única herramienta MCP llamada <server_name>_help para que el cliente pueda descubrir la CLI generada y sus subcomandos

Ejemplo de uso después del inicio:

# 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"}'

Los nombres de los subcomandos CLI son la conversión de snake_case a kebab-case de los nombres de las herramientas de backend (por ejemplo, getConfluencePage → get-confluence-page). El script generado solo funciona mientras mcp-compressor --cli-mode se está ejecutando. Use --cli-port si desea fijar el puente local a un puerto específico.

Opciones avanzadas

Servidores Stdio

# 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

Servidores remotos (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

Nombres de servidor personalizados

Al ejecutar múltiples servidores MCP a través de mcp-compressor, puede añadir prefijos personalizados a los nombres de las herramientas envolventes para evitar conflictos:

# 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

Conversión de salida TOON

Use --toonify para convertir automáticamente los resultados de las herramientas de backend JSON al formato TOON.

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

Cuando --toonify está habilitado:

• Los resultados exitosos de las herramientas de backend devueltos a través de llamadas directas a herramientas se convierten a TOON si son objetos o matrices JSON

• Los resultados exitosos de las herramientas de backend devueltos a través de invoke_tool(...) también se convierten a TOON

• Las respuestas del envoltorio de get_tool_schema(...) y list_tools(...) nunca se convierten a TOON

• El texto de guía o error generado por el envoltorio de invoke_tool(...) nunca se convierte a TOON

• El texto que no es JSON se devuelve sin cambios

Modo CLI

El modo CLI está documentado en la sección dedicada Modo CLI anterior. La versión corta: use --cli-mode, dé un nombre al servidor e interactúe con el script local generado mientras mcp-compressor se está ejecutando.

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

Registro (Logging)

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

Cómo funciona

MCP Compressor actúa como un proxy transparente entre su cliente LLM y el servidor MCP subyacente:

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

En lugar de ver todas las herramientas con esquemas completos (que a menudo son miles de tokens), el LLM solo ve:

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>

Cuando el LLM necesita usar una herramienta, primero llama a get_tool_schema(tool_name) para recuperar el esquema completo, luego invoke_tool(tool_name, tool_input) para ejecutarla.

Si --toonify está habilitado, los resultados exitosos de las herramientas de backend se convierten de JSON a TOON antes de ser devueltos al cliente. Las respuestas de ayuda del envoltorio en sí no se reformatean.

En el modo CLI (--cli-mode), el compresor expone una única herramienta <server_name>_help en lugar de los envoltorios habituales. Toda la interacción real con la herramienta ocurre a través del script de shell generado mediante un puente HTTP local.

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

Detalles del nivel de compresión

La mejor elección del nivel de compresión dependerá de varios factores, incluyendo:

1. El número de herramientas en el servidor MCP - más herramientas, use más compresión.

2. Con qué frecuencia se espera que se utilicen las herramientas - si las herramientas de un servidor comprimido se usan raramente, comprímalas más para evitar consumir tokens en vano.

3. Qué tan inusuales o complejas son las herramientas - las herramientas más simples se pueden comprimir más intensamente con poca desventaja. Considere una herramienta bash simple con un solo argumento de entrada command. Cualquier LLM moderno entenderá exactamente cómo usarla después de ver solo el nombre de la herramienta y el nombre del argumento, por lo que a menos que haya una lógica interna inesperada dentro de la herramienta, se puede usar una compresión agresiva con poca desventaja.

Configuración con archivo JSON de MCP

Puede pasar una cadena JSON de configuración MCP de servidor único directamente como COMMAND_OR_URL en la CLI. Esto es especialmente útil para servidores remotos cuando desea que la configuración en sí lleve la URL, los encabezados, el transporte o los detalles del comando stdio.

Por ahora, la entrada directa de cadena JSON admite exactamente una entrada de servidor en mcpServers.

Para configurar mcp-compressor en un archivo de configuración JSON de MCP, use el siguiente patrón:

{
  "mcpServers": {
    "compressed-github": {
      "command": "mcp-compressor",
      "args": [
        "https://api.githubcopilot.com/mcp/",
        "--header",
        "Authorization=Bearer ${GH_PAT}",
        "--server-name",
        "github"
      ],
    },
    "compressed-fetch": {
      "command": "mcp-compressor",
      "args": [
        "uvx",
        "mcp-server-fetch",
        "--server-name",
        "fetch"
      ],
    }
  }
}

Esta configuración creará herramientas llamadas github_get_tool_schema, github_invoke_tool, fetch_get_tool_schema y fetch_invoke_tool, evitando conflictos de nombres cuando se usan múltiples servidores comprimidos juntos.

Con nivel de compresión:

{
  "mcpServers": {
    "compressed-fetch": {
      "command": "mcp-compressor",
      "args": [
        "uvx",
        "mcp-server-fetch",
        "--compression-level", "high"
      ],
    }
  }
}

Casos de uso

• Grandes conjuntos de herramientas: Cuando su servidor MCP expone docenas o cientos de herramientas

• Modelos con límite de tokens: Maximice la ventana de contexto disponible para la conversación real

• Optimización de costes: Reduzca los costes de tokens para el uso de API de pago por token

• Rendimiento: Respuestas iniciales más rápidas con un contexto más pequeño

• Configuraciones de múltiples servidores: Úselo con múltiples servidores MCP sin abrumar el contexto

Referencia de línea de comandos

Usage: mcp-compressor [OPTIONS] COMMAND_OR_URL

  Run the MCP Compressor proxy server.

  This is the main entry point for the CLI application. It connects to an MCP
  server (via stdio, HTTP, or SSE) and wraps it with a compressed tool
  interface.

Arguments:
  COMMAND_OR_URL  The URL of the MCP server to connect to for streamable HTTP
                  or SSE servers, or the command and arguments to run for
                  stdio servers. Example: uvx mcp-server-fetch  \[required]

Options:
  --cwd TEXT                      The working directory to use when running
                                  stdio MCP servers.
  -e, --env TEXT                  Environment variables to set when running
                                  stdio MCP servers, in the form
                                  VAR_NAME=VALUE. Can be used multiple times.
                                  Supports environment variable expansion with
                                  ${VAR_NAME} syntax.
  -H, --header TEXT               Headers to use for remote (HTTP/SSE) MCP
                                  server connections, in the form Header-
                                  Name=Header-Value. Can be use multiple
                                  times. Supports environment variable
                                  expansion with ${VAR_NAME} syntax.
  -t, --timeout FLOAT             The timeout in seconds for connecting to the
                                  MCP server and making requests.  \[default:
                                  10.0]
  -c, --compression-level [max|high|medium|low]
                                  The level of compression to apply to tool
                                  the tools descriptions of the wrapped MCP
                                  server.  \[default: medium]
  -n, --server-name TEXT          Optional custom name to prefix the wrapper
                                  tool names (get_tool_schema, invoke_tool,
                                  list_tools). The name will be sanitized to
                                  conform to MCP tool name specifications
                                  (only A-Z, a-z, 0-9, _, -, .).
  -l, --log-level [debug|info|warning|error|critical]
                                  The logging level. Used for both the MCP
                                  Compressor server and the underlying MCP
                                  server if it is a stdio server.  \[default:
                                  WARNING]
  --toonify                       Convert JSON backend tool responses to TOON
                                  format automatically.
  --cli-mode                      Start in CLI mode: expose a single help MCP
                                  tool, start a local HTTP bridge, and generate
                                  a shell script for interacting with the
                                  wrapped server via CLI. --toonify is
                                  automatically enabled in this mode.
  --cli-port INTEGER              Port for the local CLI bridge HTTP server
                                  (default: random free port).
  --install-completion            Install completion for the current shell.
  --show-completion               Show completion for the current shell, to
                                  copy it or customize the installation.
  --help                          Show this message and exit.