headroom MCPサーバー

概要

Headroomは、AIエージェントやコーディングツールがLLM（大規模言語モデル）へ送るデータを、届く前にインテリジェントに圧縮する「コンテキスト最適化レイヤー」です。ツールの実行結果・データベースのクエリ結果・ファイルの読み込み内容・RAG（手持ちの資料をAIに読ませて答えさせる仕組み）のチャンクなど、AIが読むあらゆるデータを圧縮し、同じ回答を得ながらトークン数を60〜95%削減します。Pythonライブラリ・ローカルプロキシ・MCPサーバーの3形態で動作し、コードの変更ゼロでも導入できます。

AIコーディングツールのコストが従量課金に移行しつつある中、ツール呼び出しの多いエージェントセッションでは1回のデバッグだけで数万トークンが費やされることがあります。Headroomはその「無駄なトークン」を自動検出・削除し、AIが見るノイズを減らすことで応答速度の向上とコスト削減を同時に実現します。Apache 2.0ライセンスで商用利用も無料であり、GitHub上で約5.9万スターを獲得するほど急速に注目を集めているプロジェクトです。

主な機能

• MCPサーバーとして3つのツールを提供：headroom_compress（圧縮）・headroom_retrieve（元データ取得）・headroom_stats（節約統計）をClaude Code・Cursor・Codexなど任意のMCP対応ツールから呼び出せます。プロキシ不要で単体動作します。
• コンテンツタイプ自動検出と専用圧縮エンジン：JSON・コード・ログ・テキスト・差分・HTMLを自動判別し、最適なアルゴリズムへルーティングします。JSONにはSmartCrusher（統計的異常検知で重要行を保持）、ソースコードにはAST（構文木）解析ベースのCodeCompressorを使用します。
• 可逆圧縮（CCR：Compress-Cache-Retrieve）：圧縮してもオリジナルデータはローカルに保存され、AIが詳細を必要とすればheadroom_retrieveで即座に取り出せます。データが永久に失われることはありません。
• ゼロコード変更のドロップインプロキシ：headroom proxyを起動してAPIのベースURLをhttp://localhost:8787に向けるだけで、既存アプリに一切手を加えずすべてのリクエストを圧縮できます。OpenAI・Anthropic・AWS Bedrock・Google Vertex AI・Azure OpenAIなど100以上のプロバイダーに対応します。
• コーディングエージェントのラップ起動：headroom wrap claudeなどのコマンド一発で、Claude Code・Codex・Cursor・Aider・GitHub Copilot CLIをProxy経由で起動し、すべてのツール出力を自動圧縮できます。
• リアルタイム節約ダッシュボード：headroom dashboardコマンドでプロキシ動作中のトークン削減量・推定コスト節約額をリアルタイムで確認できます。headroom perfで過去ログの分析も可能です。
• 主要フレームワーク統合：LangChain・Agno・Strands・LiteLLM（100以上のプロバイダー対応）・Vercel AI SDK・OpenAI SDK・Anthropic SDKと統合できます。マルチエージェント間でのコンテキスト共有（SharedContext）や会話の失敗学習（headroom learn）機能も備えています。

料金プラン

> 注意：リポジトリのすべてのコードはApache 2.0ライセンスで公開されており、マネージドオプションは「自分でデプロイ・運用したくないチーム向け」の有償サービスです。個人・商用プロジェクトともに無料で利用できます。

導入方法

ステップ1：インストール（Python 3.10以上が必要）

# 推奨：全機能込みでインストール
pip install "headroom-ai[all]"

# または uv を使う場合
uv tool install "headroom-ai[all]"

# TypeScript SDK（CLIは含まれない）
npm install headroom-ai

ステップ2：使い方を選ぶ

# ① MCPサーバーとして Claude Code に登録する（最もシンプル）
headroom mcp install
# → Claude Code を再起動すると headroom_compress などが使えるようになる

# ② コーディングエージェントをラップして起動する
headroom wrap claude    # Claude Code
headroom wrap codex     # OpenAI Codex CLI
headroom wrap cursor    # Cursor
headroom wrap aider     # Aider

# ③ ドロップインプロキシとして起動（コード変更ゼロ）
headroom proxy --port 8787
# 以降は ANTHROPIC_BASE_URL=http://localhost:8787 などを設定するだけ

ステップ3：動作確認

headroom doctor       # 設定の健全性チェック
headroom dashboard    # リアルタイムで節約額を確認（プロキシ起動中）

Dockerで使う場合

docker pull ghcr.io/chopratejas/headroom:latest
docker run -p 8787:8787 ghcr.io/chopratejas/headroom:latest

こんな人におすすめ

• AIコーディングツールの月額料金が高くなってきた個人開発者：Claude CodeやCodexをヘビーに使っており、ツール呼び出しのたびにトークン消費が気になっている方。headroom wrap claude一発で導入でき、ダッシュボードで節約額をリアルタイム確認できます。
• RAGやAPIレスポンスを扱うAIアプリを作っている人：データベースやAPIから取得した大量のJSONをそのままAIに渡している場合、SmartCrusherが自動的に重複を削除・統計要約します。コードを書かずにプロキシを挟むだけで適用できます。
• 長時間動くAIエージェントを開発・運用している人：セッションが長くなるほどコンテキストが積み上がり、コストが指数的に増えます。Headroomの可逆圧縮とRollingWindowが自動的に古い情報を整理し、セッションを長く・安く保ちます。
• LangChainやVercel AI SDKなど既存のフレームワークを使っているビルダー：HeadroomChatModelやwithHeadroom()のワンライナーラッパーで既存コードをほぼ変えずに圧縮を組み込めます。

よくある質問

Q. 圧縮することでAIの回答精度が下がりませんか？ A. 公式ベンチマークでは、数学推論（GSM8K）でベースラインと同スコア、読解（SQuAD v2）で19%圧縮時も97%の精度を維持しています。また圧縮はすべて可逆で、AIが詳細を必要と判断すればheadroom_retrieveでオリジナルを取得できるため、情報が永久に失われることはありません。

Q. プロキシモードとMCPサーバーモードの違いは何ですか？ A. プロキシモードはHTTPレベルでLLMへの全トラフィックを自動圧縮します（AIが関与しない）。MCPサーバーモードはAI自身が必要に応じてheadroom_compressツールを呼び出して圧縮します。前者はゼロコード変更で全リクエストに適用、後者はプロキシなしで軽量に動作できるという違いがあります。

Q. OpenAI・Anthropic以外のLLMプロバイダーでも使えますか？ A. はい。AWS Bedrock・Google Vertex AI・Azure OpenAI・OpenRouterのほか、LiteLLM経由で100以上のプロバイダー（Together・Groq・Fireworks・Ollama・vLLMなど）に対応しています。

Q. 商用プロダクトに組み込んでも大丈夫ですか？ A. Apache 2.0ライセンスのため、商用利用・再配布・改変すべて無料で可能です。ロイヤリティや自社コードの公開義務はありません。