【完全ガイド】codebase-memory-mcpでClaude Codeのトークン消費を99%削減する — MCPコードグラフ実践入門

Claude Codeに大規模リポジトリを触らせたことがある方なら、一度はこの恐怖を経験したはずです。「この関数の影響範囲を調べて」と依頼した瞬間、ファイルを次々と読み込み続け、請求画面に表示されたトークン消費量が一桁違う——。

実際、従来のgrep+ファイル読み込みで関数の影響範囲を調査すると、約412,000トークンに達するケースがあります。それが、MCPコードグラフを使うと約3,400トークンで完結します。削減率は99.2%、約120倍の差です。

この記事では、MCP（Model Context Protocol）サーバー「codebase-memory-mcp」のインストールから実践クエリまでを一気通貫で解説します。インフラゼロ・APIキー不要・100%ローカルで動作するこのツールが、なぜここまでトークンを削減できるのかも、仕組みから丁寧に説明していきます。

この記事で分かること

• AIコーディングがトークン爆発を起こす構造的な理由
• tree-sitterによるAST解析とコードグラフの仕組み
• 5分でできるインストールとClaude Codeへの接続手順
• trace_path / find_dead_code などの実践クエリ集
• インフラゼロ・API不要・100%ローカルで完結する理由

1. なぜAIコーディングは「トークン爆発」を起こすのか

Claude Codeの設計上の宿命

Claude Codeには重要な設計特性があります。一度読み込んだファイルの内容は、コンテキストに永続的に蓄積されるのです。

あるファイルを読み込んでそのターンの作業が終わっても、その内容は以降のすべてのメッセージで課金対象になり続けます。「1ファイル読む = 以降すべてのターンで料金が発生する」という意味です。

さらに、MCPサーバー自体のオーバーヘッドも見逃せません。典型的な4サーバー構成では、毎メッセージに約7,000トークンの固定コストが追加されます。大規模な構成では、プロンプト入力前に5万トークン超を消費するケースも報告されています。ツール定義スキーマがコンテキストの先頭に常駐する構造上、これは避けられません。

grep探索の線形トークン消費

最も問題なのが、grep探索による連鎖的なファイル読み込みです。

grep → ファイルA読み込み → 参照先ファイルB読み込み → さらにCを読む → Dを読む...

探索が深くなるほどトークンは線形（実質は指数的）に膨張します。1つの関数の影響範囲を調査するだけで、前述の412,000トークンに達することも珍しくありません。

解決の方向性 — 「読む」から「引く」へ

この問題の本質的な解決策は、全文をコンテキストに載せるのではなく、事前計算済みの構造だけを返すという発想の転換です。この答えが「コードグラフ」です。

2. codebase-memory-mcpとは

一言で表現すると、「リポジトリ全体を属性付きグラフに変換し、AIエージェントに構造クエリを提供するMCPサーバー」です。検索エンジンではなく、構造データベースとして機能します。

2026年時点でMCPエコシステムは急成長しており、公式レジストリには9,652サーバー・28,959バージョンが登録、企業の41%が本番採用しています。しかし「トークン効率の良いMCPは少ない」というのが現実で、codebase-memory-mcpはその希少な存在です。

4つの差別化ポイント

特に「100%ローカル」という点は、社外秘コード・受託案件・金融/医療系リポジトリを扱うエンジニアにとって決定的なメリットです。Ollama等のローカルLLMと組み合わせることで、完全オフライン運用も実現できます。

3. 仕組みを理解する — tree-sitter × 静的解析 × グラフDB

tree-sitterによるAST解析

tree-sitterは高速な構文木パーサーフレームワークです。codebase-memory-mcpは158言語のグラマーをバイナリに内包しており、言語ランタイムを一切必要としません。

ASTから抽出するのは、関数定義・クラス・呼び出し・インポートといった構造情報です。例えば、以下のようなJavaScript関数は：

function getUserById(id) {
  return db.users.findOne({ id });
}

tree-sitterによってASTに変換され、「getUserByIdという関数がdb.users.findOneを呼び出している」というエッジ情報として記録されます。

さらに、tree-sitter単体では解決できない型解決・ジェネリクス・インターフェース実装は、C実装のHybrid LSP層が補完します。「速さのtree-sitter × 正確さのLSP」という役割分担です。

コードグラフのデータモデル

コードグラフは以下の要素で構成されます：

• ノード: 関数・メソッド・クラス・ファイル・HTTPルート・IaCリソース
• エッジ: 呼び出し・インポート・包含・非同期呼び出し・gRPC/GraphQLリンク

永続化にはSQLite（FTS5拡張）+ LZ4圧縮を採用。クエリレイテンシは**サブミリ秒（<1ms）**と高速です。

なぜ28M行を3分で処理できるのか

インデックスパイプラインの設計がポイントです：

LZ4圧縮読み込み → メモリ内SQLite処理 → グラフ構築 → 一括ディスク書き出し → メモリ解放

ディスクI/Oを最後に一括化することでボトルネックを解消しています。実測では、Linuxカーネルの2,800万行・7.5万ファイルを約3分でインデックス化します。

呼び出し解決の6段階戦略

解決の確実さには信頼度スコアが付与されます：

PythonやJavaScriptのような動的言語では低信頼度エッジが増える点は注意が必要です。信頼度スコアを見て結果を判断するのが実務的なアプローチです。

4. 【実践①】インストールとセットアップ（所要5分）

必要なもの / 不要なもの

必要: Claude CodeまたはCursor、対象リポジトリ、ディスク空き容量
不要: Docker、APIキー、Python/Nodeランタイム、外部DB

Step 1 — バイナリを取得する

# macOS / Linux
# curl が存在するか確認し、なければ wget にフォールバック
if command -v curl > /dev/null 2>&1; then
  curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | sh
elif command -v wget > /dev/null 2>&1; then
  wget -qO- https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | sh
else
  echo "エラー: curl または wget をインストールしてください"
  exit 1
fi

# インストール後に PATH を更新してから確認
export PATH="$HOME/.local/bin:$HOME/bin:/usr/local/bin:$PATH"
codebase-memory-mcp --version

Step 2 — Claude Codeに登録する

claude mcp add コマンドを使う方法が最も簡単です：

# codebase-memory-mcp が利用可能か確認してから登録
if command -v codebase-memory-mcp > /dev/null 2>&1; then
  claude mcp add codebase-memory-mcp -- codebase-memory-mcp serve
else
  echo "エラー: codebase-memory-mcp が見つかりません。インストールスクリプトを先に実行してください。"
  exit 1
fi

または .mcp.json を直接編集する方法もあります：

{
  "mcpServers": {
    "codebase-memory-mcp": {
      "command": "codebase-memory-mcp",
      "args": ["serve"]
    }
  }
}

プロジェクト固有の設定にはプロジェクトルートの .mcp.json、全プロジェクト共通にしたい場合はユーザースコープの settings.json を使い分けてください。

Step 3 — 接続を確認する

Claude Codeを再起動し、/mcp コマンドでツール一覧に codebase-memory-mcp が表示されれば成功です。表示されない場合は、バイナリのパスが通っているか・実行権限があるかを確認してください。

5. 【実践②】初回インデックス作成

リポジトリをインデックス化する

Claude Code上で以下のように依頼するか：

codebase-memory-mcpを使って、このリポジトリをインデックス化してください。

または直接コマンドで実行します：

codebase-memory-mcp index /path/to/your/repo

規模別の所要時間の目安は、小規模（〜1万行）で数秒、中規模（〜100万行）で数十秒、Linuxカーネル級（2800万行）で約3分です。

除外設定でノイズを削る

node_modules・vendor・ビルド成果物・生成コードは必ず除外しましょう。グラフ品質の向上とインデックス時間の短縮、両方に効きます：

codebase-memory-mcp index /path/to/repo \
  --exclude node_modules \
  --exclude .next \
  --exclude dist \
  --exclude vendor

インデックス結果を検証する

最初の1手として get_architecture() を実行し、言語分布・ファイル数・シンボル数が想定と合っているかを確認します。新規参画したリポジトリでは特に有効です。

6. 【実践③】主要ツールを使いこなす

trace_path() — 関数の呼び出しチェーンを追う

最も使用頻度が高いツールです。バグ修正の影響範囲調査に絶大な力を発揮します：

trace_path("processOrder", direction="inbound")

Before（従来のgrep）: processOrderを呼ぶファイルを探す → 読む → そこから呼ばれる別の関数を探す → 読む... → 合計約412,000トークン

After（グラフクエリ）: 1クエリで呼び出し元ツリーを全件取得 → 約3,400トークン

get_architecture() — 全体像を一撃で把握

言語分布・ホットスポット関数・コミュニティ（クラスタ）構造を一度に取得します。新規参画したリポジトリの初日に「まずこれを実行する」が定番ムーブになります。

find_dead_code() — 呼び出し元ゼロの関数を洗い出す

リファクタリング前の棚卸しに不可欠です：

find_dead_code(confidence_threshold=0.7)

ただし、DIコンテナで注入されるクラス・リフレクション経由の呼び出し・テスト専用関数は誤検出しやすいため、ホワイトリストで管理することをお勧めします。

detect_changes() — 変更の影響範囲とリスク分類

Git差分をシンボル単位にマッピングし、リスクレベルを分類します。PRのコードレビュー前チェックに組み込むと、レビュワーが着目すべき箇所を素早く特定できます。

Semantic Search — 意味で探す

nomic-embed-codeによる意味検索で、「認証まわりの処理どこ？」のような曖昧な問いに対応します。埋め込み処理も含めて完全ローカルで完結する点が強みです。

BM25全文検索 — SQLite FTS5 + camelCase対応

シンボル名が分かっているときの最速手段です。getUserByIdのようなcamelCaseを自動分割して検索できる点は、コード専用の工夫といえます。

7. トークン削減の実測と根拠

直接比較

この差が生まれる理由は明快です。従来手法では「探索コスト = 読み込んだ全文」ですが、グラフでは「探索コスト = 事前計算済みエッジのトラバース結果のみ」です。インデックス作成時に一度だけコストを前払いし、以降の探索は無料に近い状態になります。

学術ベンチマークによる裏付け（arXiv: 2603.27277）

31の実リポジトリを対象にした2026年3月の研究では：

トレードオフを正直に見る

品質スコアは0.92から0.83に低下します。グラフが返すのは「構造」であって「実装の詳細」ではないためです。

実務的な併用戦略としては、「グラフで範囲を絞り、必要な数ファイルだけ全文を読む」アプローチが有効です。10ファイルではなく2ファイルを精読するだけで、品質を保ちながらトークンを大幅に削減できます。

8. 実務ワークフローへの組み込み方

CLAUDE.mdに書いておくべきルール

エージェントに「まずグラフに聞く、それから読む」を徹底させるには、CLAUDE.mdへの明示的な指示が効果的です：

## コード調査のルール

1. 関数の影響範囲・呼び出し元を調べる場合は、必ずまず `trace_path()` を使うこと
2. リポジトリの全体構造を把握するには `get_architecture()` から始めること
3. ファイルの全文読み込みは、グラフクエリで対象を絞り込んだ後の最小限に限定すること
4. `grep` や `find` でファイルを順次読み込む探索は禁止

典型的な4パターン

バグ修正の影響範囲調査: trace_path(inbound) → 影響関数リスト → 該当ファイルのみ精読

新規参画リポジトリのオンボーディング: get_architecture() → ホットスポットから読む順序を決める

リファクタリング前の棚卸し: find_dead_code() + trace_path で削除可否を判定

コードレビュー支援: detect_changes() をPRテンプレートのチェック項目に組み込む

9. よくあるトラブルと対処法

インデックスが遅い / メモリを食う

除外設定を見直し、node_modules・dist・.gitを確実に除外してください。モノレポの場合は、一度に全体をインデックス化せず、サービスごとに分割するのが効果的です。

呼び出しエッジが見つからない

動的ディスパッチ・リフレクション・DIコンテナに弱い点は設計上の制約です。信頼度スコアを0.5以上でフィルタリングし、低信頼度エッジは参考程度に扱うのが実務的なアプローチです。

Claude Codeがグラフを使ってくれない

CLAUDE.mdへの明示的な指示と、ツール定義のオーバーヘッドを減らすためのMCPサーバー数の絞り込みが有効です。登録するMCPサーバーを必要最小限にすることで、Claude Codeが各ツールを選択しやすくなります。

まとめ — 「読ませない」ことがAIコーディングの最適化になる

トークン削減の本質は圧縮ではありません。そもそもファイルを読ませない設計です。

tree-sitterで全言語を横断的に解析し、コードグラフに構造を事前計算し、100%ローカルで完結させる——この組み合わせが、codebase-memory-mcpの合理性の核心です。

今日すぐ始めるなら、この3ステップです：

1. curl -fsSL ... | sh でバイナリをインストール
2. claude mcp add でClaude Codeに登録
3. get_architecture() でリポジトリの全体像を把握

次の大規模リポジトリとの対話が、これまでとは別物になるはずです。

FAQ

Q. APIキーやDockerは本当に不要ですか？
A. はい。単一の静的バイナリで動作し、外部サービスへの依存は一切ありません。

Q. 対応言語は何言語ですか？
A. tree-sitterの158言語グラマーをバイナリに内包しており、主要言語はすべてカバーされています。

Q. 巨大モノレポでも動きますか？
A. Linuxカーネル（2,800万行・7.5万ファイル）を約3分でインデックス化した実績があります。

Q. コードが外部に送信されることはありますか？
A. ありません。すべての処理はローカルで完結します。

Q. ローカルLLMと組み合わせられますか？
A. はい。Ollama等のローカルLLMと組み合わせることで、完全オフラインの開発環境を構築できます。

参考リソース

• codebase-memory-mcp GitHub
• MCP公式ドキュメント
• tree-sitter公式
• 参照論文: arXiv:2603.27277（2026年3月）