mcp-compressor

MCP 도구가 소비하는 토큰을 줄이기 위한 MCP 서버 래퍼입니다.

• Github 저장소: https://github.com/atlassian-labs/mcp-compressor/

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

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

• TypeScript 패키지 코드: https://github.com/atlassian-labs/mcp-compressor/blob/main/typescript/

• 블로그: https://www.atlassian.com/blog/developer/mcp-compression-preventing-tool-bloat-in-ai-agents/

📋 새로운 기능

2026-04-06 — TypeScript 구현

동일한 압축 개념, OAuth 지원, 프로세스 내 런타임 API 및 TypeScript CLI 모드를 갖춘 TypeScript 구현을 추가했습니다.

2026-04-06 — 단일 서버 MCP 설정 JSON 문자열

COMMAND_OR_URL은 이제 단일 MCP 설정 JSON 문자열이 될 수 있습니다. 현재로서는 mcpServers에 정확히 하나의 서버가 포함되어야 하며, 명시적으로 전달되지 않는 한 해당 키가 기본 --server-name이 됩니다.

2026-03-24 — CLI 모드

--cli-mode — 래핑된 모든 MCP 서버를 로컬 CLI로 변환합니다. 실행 가능한 셸 스크립트(Unix) 또는 .cmd 파일(Windows)을 생성하여 에이전트와 사용자가 구조화된 도구 호출 대신 익숙한 명령줄 규칙을 통해 백엔드와 상호 작용할 수 있도록 합니다.

2026-03-24 — TOON 출력

--toonify — 래핑된 백엔드 도구의 JSON 응답을 JSON의 대안으로 사람이 읽기 쉽고 LLM이 이해하기 쉬운 TOON 형식으로 자동 변환합니다.

개요

MCP Compressor는 기존 Model Context Protocol (MCP) 서버를 래핑하고 도구 설명을 압축하여 토큰 소비를 크게 줄여주는 프록시 서버입니다. 전체 스키마가 포함된 모든 도구를 언어 모델에 직접 노출하는 대신, 다음과 같은 2단계 인터페이스를 제공합니다.

1. get_tool_schema(tool_name) - 필요할 때 특정 도구의 전체 스키마를 검색합니다.

2. invoke_tool(tool_name, tool_input) - 제공된 인수로 도구를 실행합니다.

이 접근 방식은 전체 기능을 유지하면서 초기 컨텍스트에서 전송되는 토큰 수를 획기적으로 줄입니다.

왜 필요한가요?

MCP 서버는 폭발적인 인기를 얻고 있지만, 도구 설명이 모든 LLM 요청에서 상당한 토큰을 소비합니다. 예를 들어:

• 공식 GitHub MCP 서버는 94개의 도구를 노출하며 17,600 토큰을 소비합니다.

• 공식 Atlassian MCP 서버는 약 10,000 토큰을 소비합니다.

도구 설명만으로 3만 개 이상의 토큰이 소모되므로, 프롬프트 캐싱에 따라 요청당 1~10센트의 비용이 발생할 수 있습니다. MCP Compressor는 수십 개의 도구를 단 2개의 래퍼 도구로 대체하여 70~97%의 토큰 절감을 달성하면서도 전체 기능을 유지합니다. 이를 통해 다음이 가능해집니다:

• 컨텍스트 창을 초과하지 않고 많은 MCP 서버 추가

• 토큰 기반 API 가격 책정에서 상당한 비용 절감

• 에이전트에 여러 서버에 걸쳐 수백 또는 수천 개의 도구 제공 지원

기능

• Python + TypeScript 구현: 성숙한 Python 구현과 Node.js 소비자를 위한 TypeScript 패키지 제공

• 토큰 절감: 압축 수준 및 도구 수에 따라 도구 설명을 최대 99%까지 압축

• 다양한 압축 수준: low, medium, high, max 중에서 선택 가능

• 범용 호환성: 모든 MCP 서버(stdio, HTTP, SSE)와 작동

• TOON 출력 변환: --toonify를 사용하여 JSON 백엔드 도구 결과를 TOON으로 선택적 변환

• CLI 모드: --cli-mode를 사용하여 모든 MCP 서버를 로컬 CLI로 변환 — 익숙한 명령줄 구문을 통해 백엔드와 상호 작용할 수 있는 셸 스크립트 생성

• 기능 손실 없음: 모든 도구는 래퍼 인터페이스를 통해 완전히 액세스 가능

• 쉬운 통합: 기존 MCP 서버를 위한 드롭인 대체제

Python vs TypeScript

현재 가장 성숙한 기능 세트를 원하시면 Python 구현을 사용하세요. Node.js 네이티브 사용, 프로세스 내 임베딩 또는 더 긴밀한 TypeScript 생태계 통합을 원하시면 TypeScript 구현을 사용하세요.

설치

pip 또는 uv를 사용하여 설치하세요:

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

빠른 시작

기본 사용법

명령어나 URL을 제공하여 모든 MCP 서버를 래핑하세요:

# 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

사용 가능한 인수에 대한 자세한 문서는 uvx mcp-compressor --help를 참조하세요.

압축 수준

--compression-level 또는 -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

CLI 모드

래핑된 백엔드가 로컬 명령줄 도구처럼 작동하기를 원한다면 여기서 시작하세요:

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

그런 다음 생성된 CLI 스크립트를 사용하세요:

atlassian --help

--cli-mode는 래핑된 백엔드를 여러 MCP 도구로 노출하는 대신, 검색을 위한 단일 도움말 도구가 있는 로컬 CLI로 변환합니다. 이는 에이전트가 셸 스타일 인터페이스를 통해 작업하기를 원하거나, 백엔드 서버가 직접적인 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

CLI 모드가 중요한 이유

• 여러 도구 대신 하나의 도구: MCP 클라이언트는 래퍼 도구 세트 대신 단일 <server_name>_help 도구를 봅니다.

• 자연스러운 셸 UX: 백엔드 도구는 JSON 스키마에서 파생된 플래그가 있는 CLI 하위 명령이 됩니다.

• 에이전트에 적합: 에이전트는 도움말을 검사한 다음 전체 MCP 도구 표면을 컨텍스트에 유지하지 않고도 로컬 명령을 반복적으로 호출할 수 있습니다.

• OAuth 지원: 래핑된 백엔드에 OAuth가 필요한 경우, CLI 모드는 로컬 CLI를 생성하기 전에 해당 연결 흐름을 수행합니다.

• 기본 TOON: --toonify는 간결하고 읽기 쉬운 출력을 위해 CLI 모드에서 자동으로 활성화됩니다.

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

CLI 모드가 시작되면 다음을 수행합니다:

1. 필요한 경우 OAuth를 포함하여 래핑된 백엔드 서버에 연결합니다.

2. 127.0.0.1:<port>에서 로컬 HTTP 브리지를 시작합니다.

3. 실행 가능한 스크립트를 생성합니다. Unix의 경우 일반적으로 PATH에서 사용 가능한 경우 ~/.local/bin/<name>에, 그렇지 않으면 현재 디렉토리에 작성됩니다. Windows의 경우 PATH의 적절한 디렉토리에 .cmd 런처를 작성합니다.

4. 클라이언트가 생성된 CLI와 해당 하위 명령을 검색할 수 있도록 <server_name>_help라는 단일 MCP 도구를 노출합니다.

시작 후 사용 예시:

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

CLI 하위 명령 이름은 백엔드 도구 이름을 snake_case에서 kebab-case로 변환한 것입니다(예: getConfluencePage → get-confluence-page). 생성된 스크립트는 mcp-compressor --cli-mode가 실행되는 동안에만 작동합니다. 로컬 브리지를 특정 포트에 고정하려면 --cli-port를 사용하세요.

고급 옵션

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

원격 서버 (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

사용자 지정 서버 이름

mcp-compressor를 통해 여러 MCP 서버를 실행할 때, 충돌을 방지하기 위해 래퍼 도구 이름에 사용자 지정 접두사를 추가할 수 있습니다:

# 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 출력 변환

--toonify를 사용하여 JSON 백엔드 도구 결과를 TOON 형식으로 자동 변환하세요.

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

--toonify가 활성화되면:

• 직접 도구 호출을 통해 반환된 성공적인 백엔드 도구 결과가 JSON 객체나 배열인 경우 toonify됩니다.

• invoke_tool(...)을 통해 반환된 성공적인 백엔드 도구 결과도 toonify됩니다.

• get_tool_schema(...) 및 list_tools(...)의 래퍼 응답은 절대 toonify되지 않습니다.

• invoke_tool(...)에서 래퍼가 생성한 안내 또는 오류 텍스트는 절대 toonify되지 않습니다.

• JSON이 아닌 텍스트는 변경되지 않고 반환됩니다.

CLI 모드

CLI 모드는 위의 CLI 모드 섹션에 문서화되어 있습니다. 요약하자면, --cli-mode를 사용하고 서버에 이름을 지정한 다음 mcp-compressor가 실행되는 동안 생성된 로컬 스크립트와 상호 작용하세요.

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

로깅

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

작동 원리

MCP Compressor는 LLM 클라이언트와 기본 MCP 서버 사이에서 투명한 프록시 역할을 합니다:

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

전체 스키마가 포함된 모든 도구(종종 수천 개의 토큰)를 보는 대신, LLM은 다음만 봅니다:

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>

LLM이 도구를 사용해야 할 때, 먼저 get_tool_schema(tool_name)를 호출하여 전체 스키마를 검색한 다음 invoke_tool(tool_name, tool_input)을 호출하여 실행합니다.

--toonify가 활성화되면 성공적인 백엔드 도구 결과는 클라이언트로 반환되기 전에 JSON에서 TOON으로 변환됩니다. 래퍼 도우미 응답 자체는 다시 포맷되지 않습니다.

CLI 모드(--cli-mode)에서 압축기는 일반적인 래퍼 대신 단일 <server_name>_help 도구를 노출합니다. 모든 실제 도구 상호 작용은 로컬 HTTP 브리지를 통해 생성된 셸 스크립트를 통해 발생합니다.

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

압축 수준 세부 정보

최적의 압축 수준 선택은 다음을 포함한 여러 요인에 따라 달라집니다:

1. MCP 서버의 도구 수 - 도구가 많을수록 더 많은 압축을 사용하세요.

2. 도구 사용 빈도 예상 - 압축된 서버의 도구가 거의 사용되지 않는다면, 토큰 낭비를 방지하기 위해 더 많이 압축하세요.

3. 도구의 복잡성 - 더 간단한 도구는 큰 손실 없이 더 많이 압축할 수 있습니다. 단일 입력 인수 command를 가진 간단한 bash 도구를 고려해 보세요. 현대적인 LLM이라면 도구 이름과 인수 이름만 보고도 사용 방법을 정확히 이해할 것이므로, 도구 내부에 예상치 못한 내부 로직이 없는 한 큰 손실 없이 공격적인 압축을 사용할 수 있습니다.

MCP JSON 파일을 사용한 설정

CLI에서 COMMAND_OR_URL로 단일 서버 MCP 설정 JSON 문자열을 직접 전달할 수도 있습니다. 이는 설정 자체가 URL, 헤더, 전송 또는 stdio 명령 세부 정보를 포함하기를 원할 때 원격 서버에 특히 유용합니다.

현재 직접 JSON 문자열 입력은 mcpServers에서 정확히 하나의 서버 항목을 지원합니다.

MCP JSON 설정 파일에서 mcp-compressor를 설정하려면 다음 패턴을 사용하세요:

{
  "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"
      ],
    }
  }
}

이 설정은 github_get_tool_schema, github_invoke_tool, fetch_get_tool_schema, fetch_invoke_tool이라는 이름의 도구를 생성하여 여러 압축 서버를 함께 사용할 때 이름 충돌을 방지합니다.

압축 수준 설정:

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

사용 사례

• 대규모 도구 세트: MCP 서버가 수십 또는 수백 개의 도구를 노출할 때

• 토큰 제한 모델: 실제 대화를 위해 사용 가능한 컨텍스트 창을 최대화

• 비용 최적화: 토큰당 지불 API 사용에 대한 토큰 비용 절감

• 성능: 더 작은 컨텍스트로 더 빠른 초기 응답

• 다중 서버 설정: 컨텍스트를 압도하지 않고 여러 MCP 서버와 함께 사용

명령줄 참조

G