claude-context（Zilliz製）使い方完全ガイド｜コードベース全体をセマンティック検索するMCPプラグイン【2026年最新】

claude-context は、ベクトルDBの Milvus を開発する Zilliz 社がオープンソースで公開しているMCPサーバーで、AIコーディングエージェントに「コードベース全体のセマンティック検索」機能を追加するプラグインです。公式評価ではトークン使用量を平均39.4%・ツール呼び出し回数を36.1%削減できると報告されています（2026年6月現在のGitHubスター数：11,600以上）。

この記事でわかること

• claude-context の構成（MCPサーバー・埋め込みモデル・ベクトルDBの3層）
• Claude Code・Cursor・Windsurf・Gemini CLI など主要クライアントでの設定手順
• OpenAI埋め込み＋Zilliz Cloud 構成 vs Ollama＋ローカルMilvus（完全オフライン）の選び方
• 企業・機密コード向けのセキュリティ要件と推奨構成
• Serena など類似MCPとの使い分け・実運用上のトラブル対処

想定読者：Claude Code や Cursor でコンテキスト不足に悩むエンジニア、大規模モノレポをAIと一緒にデバッグしたいチーム、社外秘コードをオフライン環境でAIコーディング支援したい情報システム担当者。

claude-context とは：3行サマリー

claude-context は GitHub で公開されている Zilliz 社製のオープンソースMCPサーバーです。コードベースをベクトル化してAIコーディングエージェントに「セマンティックなリポジトリ横断検索」を提供するプラグインで、MITライセンスで商用利用可能。npm パッケージ @zilliz/claude-context-mcp として配布されており、Claude Code・Cursor・Windsurf・Gemini CLI など主要なMCPクライアントから利用できます。

公式が強調している3つの技術的特徴：

• ハイブリッド検索：BM25（キーワードマッチ）と密ベクトル（意味検索）を組み合わせた検索
• ASTベースのコード分割：tree-sitter パーサで関数・クラス単位に意味的なチャンクへ分割（デフォルト2,500行。対応外言語は文字ベースフォールバック）
• Merkle Treeベースの差分インデックス：変更されたファイルだけを再インデックスするため大規模リポジトリでも高速

「ファイルを都度読ませる」のではなく「ベクトルDBに事前登録して関連チャンクだけを渡す」発想なので、数万行〜十数万行規模のモノレポでもコンテキストウィンドウを枯渇させにくいのが特徴です。

claude-context の仕組み（3つのコンポーネント）

出典: zilliztech/claude-context GitHub公式

claude-context を理解しづらくしている最大の原因は、動作に 3つの独立したコンポーネントが必要な点です。ここを分けて把握することが最初のポイントです。

動作の流れ：

1. index_codebase が呼ばれると、claude-context が対象ディレクトリを AST で関数・クラス単位に分割
2. 各チャンクを埋め込みプロバイダーに投げてベクトル化
3. ベクトルと元コードをベクトルDBに保存
4. search_code で自然言語クエリが来たら、クエリもベクトル化してDBに類似検索
5. 上位チャンクを MCP 経由でクライアントに返す

重要：埋め込みプロバイダーに OpenAI などクラウドAPIを選ぶと、コードチャンクが外部に送信されます。社外秘コードを扱う場合は、Ollama＋ローカルMilvus の構成を使う必要があります。

claude-context が提供する4つのMCPツール

対応プログラミング言語（現行14言語）

TypeScript / JavaScript / Python / Java / C++ / C# / Go / Rust / PHP / Ruby / Swift / Kotlin / Scala / Markdown

できること・できないこと

出典: zilliztech/claude-context GitHub公式

できること

• 自然言語でのコード検索：「ユーザー認証のJWT検証をしている場所」のような意味ベース検索
• マルチプロジェクト対応：各コードベースは絶対パスをキーにして管理。複数リポジトリを混在させても衝突しない
• 大規模リポジトリのインクリメンタル更新：Merkle Tree による差分検出で変更ファイルだけ再インデックス
• 主要14言語のAST対応：関数・クラス単位の意味的なチャンク分割
• ローカル完結運用：Ollama（埋め込み）＋Milvus Standalone（ベクトルDB）で外部送信なしに運用可能
• トークン削減効果：公式評価で平均39.4%削減・ツール呼び出し36.1%削減を実証（Django YearLookup バグ修正で93%削減、Xarray swap_dims バグで62%削減の事例あり）

できない・不得意なこと

• シンボル単位のジャンプ・参照元追跡：LSP ベースの機能は Serena など別MCPが得意領域
• リアルタイム同期：ファイル変更の反映に数秒〜十数秒の遅延がある（Merkle Tree 差分検出の仕様）
• Node.js 24 以上での動作：現時点では Node.js 20.x または 22.x のみ対応。23.x 以降・24 以上は非対応
• Milvus 2.3.x との組み合わせ：SparseFloatVector 非対応のため使用不可
• ベクトルDB なしでの単独動作：Milvus または Zilliz Cloud が別途必要
• 完全一致検索の保証：ハイブリッド検索でも完全一致のキーワードマッチを保証するわけではない
• 大規模リポジトリの初回インデックス時間：12,000ファイル規模で3〜6分かかる場合がある

料金：本体は無料、実運用費は「埋め込みAPI＋ベクトルDB」で決まる

出典: Zilliz 公式サイト

claude-context 本体はOSS（MITライセンス）で無料です。実運用コストは埋め込みAPIとベクトルDBの選択によって決まります。

コスト感の目安

• 完全無料で運用したい → Ollama + Milvus Standalone（Docker）
• とりあえず試したい → OpenAI 埋め込み + Zilliz Cloud 無料枠（サインアップで$100クレジット付与あり）
• チームで本番運用したい → OpenAI または VoyageAI 埋め込み + Zilliz Cloud 有料プラン

⚠️ 大規模モノレポ（10万行超）では、初回インデックス時の埋め込みAPI料金が一時的に膨らむ点に注意。長期運用前に Zilliz Cloud 公式料金ページ で最新単価を確認することを推奨します。

前提条件（詰まりやすいポイント先出し）

セットアップを始める前に、次の4点を揃えておきます。

1. Node.js のバージョン：20.x または 22.x（23.x 以降・24 以上は現時点で非対応。node -v で確認）
2. 埋め込みAPIキー または Ollama のローカル環境
3. ベクトルDB の接続先（Zilliz Cloud なら URI とトークン、ローカルなら Milvus の Docker起動）
4. MCPクライアント（Claude Code / Cursor / Windsurf / Gemini CLI 等のいずれか）

Node.js のバージョン制約は特に引っかかりやすいポイントです。事前に確認してから進めてください。

使い方①：Claude Code で claude-context を使う最短セットアップ

Claude Code の場合、MCPの設定は ~/.claude.json への記述で行います。OpenAI 埋め込み + Zilliz Cloud の最短構成を示します。

ステップ1：APIキー／接続情報を用意する

• OpenAI：APIキー（sk-...）
• Zilliz Cloud：クラスタ作成後、「Connect」から URI とトークンをコピー

Zilliz Cloud の無料枠は docs.zilliz.com/docs/free-trials の手順で数分で作成できます。

ステップ2：claude-context を MCP として登録する

~/.claude.json の mcpServers に以下を追記します。

{
  "mcpServers": {
    "claude-context": {
      "command": "npx",
      "args": ["@zilliz/claude-context-mcp@latest"],
      "env": {
        "EMBEDDING_PROVIDER": "OpenAI",
        "EMBEDDING_MODEL": "text-embedding-3-small",
        "OPENAI_API_KEY": "sk-xxxxxxxxxxxx",
        "MILVUS_ADDRESS": "https://xxxx.api.gcp-us-west1.zillizcloud.com",
        "MILVUS_TOKEN": "xxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

ステップ3：Claude Code を再起動してインデックス実行

Claude Code を再起動後、チャット内で：

「/path/to/my-project をインデックスしてください」

Claude Code が index_codebase ツールを自動で呼び、バックグラウンドでインデックスが走ります。1万行規模で数分〜十数分、10万行規模では数十分かかる場合があります。

ステップ4：自然言語で検索する

「このリポジトリでJWTトークンを検証している箇所を探して」
「決済処理のエラーハンドリングをしている関数をリストアップして」

Claude Code は内部で search_code を呼び、関連チャンクだけをコンテキストに取り込んで回答します。

なお、Claude Code 自体をMCPサーバーとして外部エージェントから呼び出す構成については、claude-code-mcp 使い方ガイドで詳しく解説しています。

使い方②：Cursor / Windsurf / Gemini CLI / Codex CLI での設定

対応MCPクライアントごとに設定ファイルの場所と書式が異なります。共通部分（command・args・env）は同じで、設定ファイルの場所と形式だけが違うと捉えると整理しやすいです。

Codex CLI のみ TOML 形式で記述が必要です：

[mcp_servers.claude-context]
command = "npx"
args = ["@zilliz/claude-context-mcp@latest"]

[mcp_servers.claude-context.env]
EMBEDDING_PROVIDER = "OpenAI"
EMBEDDING_MODEL = "text-embedding-3-small"
OPENAI_API_KEY = "sk-xxxxxxxxxxxx"
MILVUS_ADDRESS = "https://xxxx.api.gcp-us-west1.zillizcloud.com"
MILVUS_TOKEN = "xxxxxxxxxxxxxxxxxxxxxxx"

GitHub 公式のMCPサーバーと組み合わせてリポジトリ操作も自動化したい場合は、github-mcp-server 使い方ガイドも参考になります。

使い方③：ローカル完結構成（Ollama + Milvus Standalone）

社外秘コードを扱う場合や、API従量課金を避けたい場合は、埋め込みもベクトルDBも完全ローカルで動かせます。外部へのコード送信が発生しない構成です。

1. Ollama で埋め込みモデルを起動

# Ollama のインストール（macOS: brew）
brew install ollama

# 埋め込みモデルの取得（代表例）
ollama pull nomic-embed-text
ollama serve

2. Milvus Standalone を Docker で起動

mkdir milvus && cd milvus
# Milvus 2.4.x 以降の安定版を使用すること（2.3.x は非対応）
curl -O https://github.com/milvus-io/milvus/releases/download/v2.5.0/milvus-standalone-docker-compose.yml
mv milvus-standalone-docker-compose.yml docker-compose.yml
docker compose up -d

デフォルトでは 19530 ポートを使用します。WSL2 環境等で競合する場合は 19531 に変更してください。

⚠️ Milvus バージョンについて：Milvus 2.3.x は SparseFloatVector 非対応のため使用不可。2.4.x 以降を使用してください。

3. claude-context 側の環境変数を切り替える

{
  "mcpServers": {
    "claude-context": {
      "command": "npx",
      "args": ["@zilliz/claude-context-mcp@latest"],
      "env": {
        "EMBEDDING_PROVIDER": "Ollama",
        "EMBEDDING_MODEL": "nomic-embed-text",
        "OLLAMA_HOST": "http://127.0.0.1:11434",
        "MILVUS_ADDRESS": "127.0.0.1:19530"
      }
    }
  }
}

この構成なら、コードは外部APIに一切送信されません。受託開発・金融・医療系の社外秘コードを扱う現場では、現実的かつ推奨される選択肢です。

主要な環境変数一覧

公式ドキュメントとソースコードで確認できる、よく使う環境変数の一覧です。

注意：MILVUS_ADDRESS を省略するとクラッシュ（Address is required エラー）が発生します。必ず明示的に指定してください。

対象ファイルの判定ルールは「サポート拡張子の集合」から「除外パターン」を引いたもので、.gitignore は自動で尊重されます。

セキュリティ・プライバシー上の注意点

1. 埋め込みAPIへのコード送信リスク

OpenAI・VoyageAI・Gemini などクラウドAPIを使う場合、コードチャンクは埋め込み生成のためにベンダーへ送信されます。各社のデータ保持・学習利用ポリシーを契約・利用規約で確認してください。社外秘コードやNDA下のコードを扱う場合は、Ollama＋ローカルMilvus 構成を選ぶのが現実的です。

2. ベクトルDB上にも「コードの原文」が残る

Milvus には埋め込みベクトルだけでなく、検索結果として返すために元のコードチャンクもペイロードとして保存されます。クラウドのベクトルDBを使う場合、データの所在地と暗号化状況を確認することが必要です。

3. APIキーの管理

MCP設定ファイル（~/.claude.json 等）に埋め込みAPIキーがプレーンテキストで入る点に注意してください。dotfiles リポジトリに誤コミットしないよう .gitignore を徹底するか、OS のキーチェーン経由で渡すなどの工夫が必要です。

業種・環境別の推奨構成

他のコード検索系MCPとの使い分け

claude-context 以外にも「AIエージェント向けのコード理解を助けるMCP」が複数あります。何をしたいかで使い分けるのが実践的です。

選び方の目安

• 「どこで何をしているか」を意味で探したい → claude-context
• 「この関数はどこから呼ばれているか」を正確に追いたい → Serena
• 外部ライブラリの使い方を聞きたい → Context7
• チームで検索結果やメモを共有したい → Cipher

実務では claude-context と Serena を併用している開発者が多く、公式ドキュメントも両者を組み合わせる構成を否定していません。

Claude Code Auto Mode との組み合わせで、claude-context で関連コードを検索しながら自律的なコード修正フローを構築するユースケースも広がっています。

よくあるトラブルと対処

Q1. index_codebase がエラーで止まる

• Node.js のバージョンが 20.x または 22.x になっているか確認（23.x 以降・24 は非対応。node -v で確認）
• Zilliz Cloud のトークンに改行や空白が混ざっていないか確認
• ローカル Milvus の場合、docker compose ps でコンテナが起動しているか確認
• MILVUS_ADDRESS を明示指定しているか確認（省略するとクラッシュ）

Q2. スナップショットが壊れてインデックスが0件になる（無限 force-reindex ループ）

ローカルの ~/.context/mcp-codebase-snapshot.json が0件を記録しながら、Milvus側にデータが残っている状態が発生することがあります。この場合、clear_index でスナップショットをリセットしてから index_codebase を再実行します。

「インデックスをクリアして、最初からインデックスし直してください」

このバグへの対処 PR は2026年時点でマージ済みのため、@latest を使っていれば改善されている可能性が高いです。

Q3. Zilliz Cloud でgRPCタイムアウトエラーが出る

Zilliz Cloud のコールドスタート時にgRPCのデフォルト15秒タイムアウトを超える場合があります。環境変数 MILVUS_COLLECTION_LIMIT_CHECK_TIMEOUT_MS を大きくすることで対処できます：

"MILVUS_COLLECTION_LIMIT_CHECK_TIMEOUT_MS": "30000"

Q4. 検索結果が的外れに感じる

• 埋め込みモデルを text-embedding-3-small から voyage-code-3（コード特化）に変更する
• HYBRID_MODE=true が有効になっているか確認
• SPLITTER_TYPE=ast が効く言語か確認（対応外の言語では langchain にフォールバック）
• 対象が1万行以下の小規模プロジェクトの場合、@ファイル名 指定の方が効果的なケースもある

Q5. インデックスが肥大化する・インデックスに時間がかかる

• CUSTOM_IGNORE_PATTERNS で node_modules/** dist/** **/*.min.js などを除外
• .gitignore 対象は自動で除外されるため、まず .gitignore を整備する
• 実際の効果が出るのは5万行以上のリポジトリが目安とされており、小規模プロジェクトではコスト対効果を再検討する

Q6. ファイル変更後すぐ反映されない

Merkle Tree による差分検出が非同期で走るため数秒〜十数秒の遅延があります（仕様）。明示的に再インデックスしたい場合は clear_index → index_codebase の順で実行します。

こんな方におすすめ / おすすめしない方

claude-context が向いている人・組織

• Claude Code・Cursor・Codex CLI で大規模リポジトリ（目安：1万行以上）を扱っていてコンテキスト不足に悩んでいる
• 「どこで似た処理をしているか」を意味ベースで横断検索したい
• モノレポを運用していて、AIエージェントにリポジトリ全体を認識させたい
• 情報システム部門の方針でローカル完結構成が必要（Ollama + Milvus で対応可能）
• Claude Code API などでトークン使用量・コストを最適化したいチーム

claude-context をおすすめしない方

• 数千行以下の小規模プロジェクト：@ファイル名 や grep 相当で十分で、ベクトルDBの運用コストが見合わない
• シンボルジャンプ・参照元追跡が主用途：Serena の方が精度が高い
• リアルタイム反映が必須：秒単位の遅延が許容できない用途には合わない
• Node.js 環境を用意できない・運用したくない：ランタイム管理がハードルなら別の手段を検討
• Milvus のインフラ管理を避けたい小規模チーム：Zilliz Cloud 無料枠では賄えない場合、運用コストが重くなりうる

よくある質問（FAQ）

Q. GitHub のスター数はどのくらい？

2026年6月時点では 11,600以上のスターを獲得しており、GitHub トレンド入りも経験しています。正確な最新値は GitHub 公式リポジトリ で確認してください。

Q. 公式の「40%トークン削減」は本当？

公式 README の評価セクションに記載されている内容で、平均39.4%削減・ツール呼び出し36.1%削減という数値です。Django の YearLookup バグ修正では93%削減、Xarray の swap_dims バグ修正では62%削減の事例が報告されています。ただし効果はリポジトリの構造・クエリの種類によって異なります。自社環境での効果測定を推奨します。

Q. VS Code 拡張機能もあるの？

はい、Zilliz 公式から VS Code Marketplace で提供されています。npm 版（MCPサーバー）と拡張機能版がありますが、提供機能の詳細は公式ドキュメントで最新状況を確認してください。

Q. 最新バージョンはどこで確認できる？

GitHub Releases ではなく、npm の @zilliz/claude-context-mcp でバージョン追跡するのが確実です。設定では @zilliz/claude-context-mcp@latest を指定することで最新版が自動取得されます。

Q. Claude Code のサブエージェントでも使える？

MCPサーバーとして登録されていれば、サブエージェント側からも同じツール（index_codebase / search_code 等）を呼び出せます。

Q. 会社のコードを学習に使われない？

埋め込みAPIをOpenAIなどクラウド側に置くと、各社のデータ保持・学習ポリシーが適用されます。学習利用を避けたい場合は各社のAPIオプトアウト設定を確認するか、Ollama + ローカルMilvus の構成を選んでください。

Q. @zilliz/claude-context-core パッケージとの違いは？

@zilliz/claude-context-mcp は MCPクライアント向けのサーバー実装です。@zilliz/claude-context-core は TypeScript から直接統合するためのライブラリパッケージで、LangChain/LangGraph などのエージェントフレームワークから直接呼び出す際に使います。

Q. チーム間でインデックスを共有できる？

コレクション名がローカルパスのMD5ハッシュになっているため、異なるマシン・開発者間でのインデックス共有は標準設定では困難です。実務では「1ホストに1つの永続MCPサーバーを立て、チームがそれを参照する」構成が推奨されています。

まとめ：claude-context を最短で導入する3つの判断ポイント

1. まず構成を決める — 試すだけなら OpenAI + Zilliz Cloud 無料枠、本格運用なら社外秘要件に応じて Ollama + ローカルMilvus を選択
2. MCPクライアント側の設定を追記する — Claude Code なら ~/.claude.json、Codex CLI のみ config.toml（TOML形式）と書式が異なる点に注意
3. インデックス → 検索の2ステップで動作確認 — 1万行規模なら数分〜十数分、10万行規模は数十分が目安。効果の実感は5万行以上が目安

公式情報の変化が速い領域のため、料金・対応バージョン・対応クライアントは Zilliz Cloud 料金ページ と GitHub 公式リポジトリ を最終確認のうえ導入してください。

関連記事

• Claude Codeとは何か全体像を把握したい方は「Claude Codeとは」
• Claude Code の料金・プランを比較したい方は「Claude Code 料金」
• MCPという仕組みそのものを理解したい方は「MCPとは（Model Context Protocol）」
• Claude Code 自体をMCPサーバーとして動かす方法は「claude-code-mcp 使い方ガイド」
• GitHub操作をMCPで自動化したい方は「github-mcp-server 使い方ガイド」
• Claude Code の自律実行モードについては「Claude Code Auto Mode とは」
• コーディング支援AIを横断比較するなら「AIコーディングツール おすすめ 比較」