How do I use mcp-compressor?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcp-compressor list available tools" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

mcp-compressor

by zakkii-k

Overview Schema Source Related Servers Discussions Admin

Python

Local

mcp-compressor

GitHub Copilot の MCP レスポンスをインターセプトし、トークン消費を削減するプロキシ。

解決する問題

問題	対策
MCP のレスポンスが大きくてトークンを食う	圧縮パイプラインで削減
ツール定義が多くて毎ターン固定コストがかかる	メタツール方式で常に2ツールだけ公開
内部・外部 MCP が混在していてインターセプトが難しい	wrap モードで一箇所に集約

Related MCP server: Refract

仕組み

圧縮パイプライン

MCP のレスポンスを以下の順で処理する。

MCP レスポンス
  ↓ TOON 変換        JSON を 36〜64% 削減（LLM 可読のまま）
  ↓ ログ重複除去      繰り返しパターンを集約、最大 98% 削減
  ↓ ログ圧縮         大量ログを先頭 / エラー / 末尾に絞る
  ↓ LLM 要約        閾値超えのみ Ollama で要約（元データ保存）
  ↓
Copilot へ返却

プロキシモード

stdio モード（デフォルト）

MCP サーバーを1つずつラップする。既存の設定に1行追加するだけ。

Copilot → mcp-compressor → 実際の MCP サーバー（子プロセス）

wrap モード

mcp.servers.json に書いた全サーバーに接続し、Copilot には1つのサーバーとして見せる。内部（stdio）・外部（SSE/HTTP）問わず一箇所でインターセプトできる。

Copilot → mcp-compressor ┬→ filesystem サーバー（stdio）
                          ├→ atlassian サーバー（SSE）
                          └→ github サーバー（SSE）

メタツール方式（デフォルト）

Copilot に公開するのは常に2ツールだけ。

mcp__list_tools(query?)              ← ツール一覧を返す（TOON 圧縮対象）
mcp__invoke_tool(server, tool, args) ← ツールを実行する

ツール定義は LLM に毎ターン送られる。ツールが多いほど固定コストが増えるため、常に2つに絞ることで削減する。

通常方式: ツール定義 × 30個 × 会話10ターン = 300回分の定義コスト
メタツール: ツール定義 × 2個 × 会話10ターン = 20回分
           + list_tools の結果（TOON 圧縮済み）が履歴に1回

セットアップ

前提条件

Windows 11
Rancher Desktop（Docker 利用のため）
Python 3.11 以上（インストール済みであれば pyenv 不要）

1. リポジトリをクローン（PowerShell）

cd C:\Users\ユーザー名\projects   # 任意のディレクトリ
git clone https://github.com/zakkii-k/mcp-compressor.git
cd mcp-compressor

以降のパス例は C:\Users\ユーザー名\projects\mcp-compressor として記載する。実際のパスに読み替えること。

2. Ollama を起動

WSL・PowerShell どちらでも同じ（Rancher Desktop が起動していれば docker が使える）。 docker compose up はリポジトリ内で実行すること。

# リポジトリ内で実行
docker compose up -d

# または docker run で起動（ディレクトリを問わない）
docker run -d `
  --name ollama `
  -p 11434:11434 `
  -v ollama_data:/root/.ollama `
  --restart unless-stopped `
  ollama/ollama:latest

モデルをダウンロード:

docker exec ollama ollama pull qwen2.5:3b

3. mcp-compressor のインストール

2通りある。Docker が一番シンプル。

A. Docker（推奨・Python 環境不要）

cd C:\Users\ユーザー名\projects\mcp-compressor
docker build -t mcp-compressor .

MCP 設定で docker run を指定するだけで動く。

B. Windows ネイティブ Python

Python が入っていれば pip だけでOK（pyenv 不要）。

cd C:\Users\ユーザー名\projects\mcp-compressor
pip install httpx pyyaml python-toon

4. mcp.json を編集

VS Code のグローバル MCP 設定は以下にある:

C:\Users\ユーザー名\AppData\Roaming\Code\User\mcp.json

グローバル設定なのでパスは絶対パスで書くこと。ワークスペースごとに設定する場合は .vscode/mcp.json を使う（相対パス可）。

stdio モード（サーバーを1つずつラップする場合）

変更前:

{
  "servers": {
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "C:\\path\\to\\dir"]
    }
  }
}

変更後（Python）:

{
  "servers": {
    "filesystem": {
      "type": "stdio",
      "command": "python",
      "args": [
        "-m", "mcp_compressor",
        "--config", "C:\\Users\\ユーザー名\\projects\\mcp-compressor\\config.yaml",
        "--",
        "npx", "-y", "@modelcontextprotocol/server-filesystem", "C:\\path\\to\\dir"
      ]
    }
  }
}

変更後（Docker）:

{
  "servers": {
    "filesystem": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "mcp-compressor",
        "--",
        "npx", "-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"
      ]
    }
  }
}

wrap モード（全サーバーを1エントリに集約する場合）

Step 1: 既存の mcp.json の servers 部分を mcp.servers.json としてリポジトリ内に保存。

C:\Users\ユーザー名\projects\mcp-compressor\mcp.servers.json

{
  "servers": {
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "C:\\path\\to\\dir"]
    },
    "atlassian": {
      "type": "sse",
      "url": "https://mcp.atlassian.com/v1/sse"
    }
  }
}

mcp.servers.example.json をコピーして編集してください。

Step 2: mcp.json を書き換え（Python）:

{
  "servers": {
    "mcp-compressor": {
      "type": "stdio",
      "command": "python",
      "args": [
        "-m", "mcp_compressor",
        "--mode", "wrap",
        "--config", "C:\\Users\\ユーザー名\\projects\\mcp-compressor\\config.yaml",
        "--mcp-config", "C:\\Users\\ユーザー名\\projects\\mcp-compressor\\mcp.servers.json"
      ]
    }
  }
}

Step 2: mcp.json を書き換え（Docker）:

{
  "servers": {
    "mcp-compressor": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "C:\\Users\\ユーザー名\\projects\\mcp-compressor\\mcp.servers.json:/app/mcp.servers.json",
        "-v", "C:\\Users\\ユーザー名\\projects\\mcp-compressor\\config.yaml:/app/config.yaml",
        "-v", "C:\\Users\\ユーザー名\\projects\\mcp-compressor\\originals:/app/originals",
        "mcp-compressor",
        "--mode", "wrap"
      ]
    }
  }
}

Copilot から見えるツール:

mcp__list_tools   → query="atlassian" で Jira 関連ツールを検索できる
mcp__invoke_tool  → server="atlassian", tool="create_issue" で実行

プレフィックス方式に戻す場合は --no-meta-tools を追加。

設定

config.yaml:

# 要約閾値（パイプライン処理後にこの文字数を超えたら LLM 要約）
threshold_chars: 5000

# 使用モデル（1行変更で切り替え）
model: "qwen2.5:3b"

# パイプラインステージ（実行順）
pipeline:
  - toon_converter      # JSON → TOON 形式（36〜64% 削減）
  - log_deduplicator    # 繰り返しパターンのログを集約
  - log_compressor      # ログの先頭/エラー/末尾を抽出
  - llm_summarizer      # LLM で要約（Ollama 必要）

推奨モデル（16GB RAM）

品質順	モデル	RAM	備考
1	`qwen2.5:7b`	~4.5GB	要約タスク最高品質
2	`qwen3:4b`	~3GB	thinking mode を自動無効化して使用
2	`gemma4:e4b`	~3GB	Google 製、バランス良好
4	`qwen2.5:3b`	~2GB	デフォルト。安定・高速

環境変数

変数	内容	デフォルト
`OLLAMA_URL`	Ollama の URL（Docker 内は自動設定済み）	`http://localhost:11434`
`MCP_MODEL`	使用モデル	`qwen2.5:3b`
`MCP_THRESHOLD`	要約閾値（文字数）	`5000`

圧縮手法の詳細

docs/compression-techniques.md を参照。

手法	削減率	LLM 不要	対象
TOON 変換	36〜64%	✅	JSON 全般
ログ重複除去	80〜98%	✅	繰り返しパターンのログ
ログ先頭/エラー/末尾	60〜80%	✅	大量ログ
LLM 要約	70〜90%	❌	汎用テキスト

テスト

Ollama なしでパイプラインと wrap モードのテストが実行できる。

pip install pytest
pytest tests/ -v

Ollama 起動後は LLM 要約テストも自動で有効になる。

プロジェクト構成

mcp-compressor/
├── mcp_compressor/
│   ├── main.py              # エントリーポイント（--mode stdio/wrap/http）
│   ├── config.py            # 設定読み込み（環境変数対応）
│   ├── pipeline/            # 圧縮パイプライン
│   │   ├── toon_converter.py
│   │   ├── log_deduplicator.py
│   │   ├── log_compressor.py
│   │   ├── json_compressor.py
│   │   ├── json_table_converter.py
│   │   └── llm_summarizer.py
│   └── proxy/
│       ├── stdio_proxy.py        # stdio モード（ローカル MCP）
│       ├── wrap_proxy.py         # wrap モード（全 MCP を集約）
│       ├── server_connection.py  # stdio/SSE サーバー接続管理
│       └── http_proxy.py         # HTTP モード（未実装・スタブ）
├── tests/
├── docs/
│   ├── setup.md
│   └── compression-techniques.md
├── config.yaml
├── mcp.servers.example.json
├── Dockerfile
└── docker-compose.yml

This server cannot be deployed

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Maintenance

ActivityInactive

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

Occludra — MCP Gateway (AI Security Gateway)
ai.occludra
Security & DLP proxy for MCP: tool-poisoning scans, PII redaction on tool args/results. Beta.
Security Agent Orchestration
1
ToolRouter B
io.github.Humanleap
The OpenRouter for tools. One MCP connection gives any AI agent 254 hosted tools, pay per call.
Agent Orchestration Autonomous Agents
471
Reasoning Commons
io.github.chenyuan35
AI Reasoning Cache & Consensus Layer with 11 MCP tools via Streamable HTTP.
AI & Machine Learning Knowledge & Memory Autonomous Agents
2
rtkcontext-mcp
com.clauxel.rtkcontext
A paid remote MCP for OpenAI Codex context compressor, built to return verdicts, receipts, usage log
AI & Machine Learning Monitoring
2

Related MCP Servers

mcp-compressor
Developer Tools AI & Machine Learning
atlassian-labs
A
license
Not graded
quality
A
maintenance
A proxy server that wraps existing MCP servers to significantly reduce token consumption by compressing tool descriptions into a two-step interface. It enables users to integrate extensive toolsets without exceeding context limits or incurring high API costs.
Updated 4 days ago (2026-09-08 21:11 UTC)
118
Apache 2.0
Refract
Developer Tools Agent Orchestration
LoudiliMed
A
license
A
quality
B
maintenance
MCP proxy that compresses tool schemas on the fly. Up to 98% token reduction, 100% signal preserved verified after every compression. Zero LLM calls, fully deterministic.
Updated 9 days ago (2026-09-03 22:49 UTC)
5
4
MIT
rtk-mcp
Browser Automation Developer Tools
KCuppens
A
license
Not graded
quality
C
maintenance
MCP proxy that filters oversized tool responses, downscaling screenshots and pruning accessibility snapshots to reduce token usage in LLM interactions.
Updated 2 months ago (2026-07-08 17:43 UTC)
MIT
MCP-Lens
Agent Orchestration Developer Tools
M8T-Jacob
A
license
Not graded
quality
C
maintenance
Acts as a proxy/router for multiple downstream MCP servers, exposing only meta-tools to the host to reduce token usage, enabling efficient search and invocation of tools from a fleet of servers.
Updated 2 months ago (2026-07-13 13:31 UTC)
18
MIT

mcp-compressor

解決する問題

仕組み

圧縮パイプライン

プロキシモード

stdio モード（デフォルト）

wrap モード

セットアップ

前提条件

1. リポジトリをクローン（PowerShell）

2. Ollama を起動

3. mcp-compressor のインストール

A. Docker（推奨・Python 環境不要）

B. Windows ネイティブ Python

4. mcp.json を編集

stdio モード（サーバーを1つずつラップする場合）

wrap モード（全サーバーを1エントリに集約する場合）

設定

推奨モデル（16GB RAM）

環境変数

圧縮手法の詳細

テスト

プロジェクト構成

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

mcp-compressor

Refract

rtk-mcp

MCP-Lens