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

claude-context は、Milvus を開発する Zilliz 社がオープンソースで公開している コード検索用のMCPサーバーです。AIコーディングエージェントにリポジトリ全体を横断したセマンティック検索能力を付与し、公式評価では「同等の検索品質のもとで約40%のトークン削減」を実証したと記載されています。本記事では、claude-context の仕組み・料金・Claude Code / Cursor / Codex CLI からの具体的な導入手順・ローカル完結構成・セキュリティ上の注意点までを、2026年4月時点の公式情報ベースで整理します。

この記事でわかること

• claude-context がどのコンポーネント（MCP／埋め込みモデル／ベクトルDB）で構成されているか
• Claude Code・Cursor・Windsurf・Codex CLI など主要クライアントでの設定手順
• OpenAI 埋め込み＋Zilliz Cloud を使う場合／Ollama＋ローカル Milvus で完全オフライン運用する場合の選び分け
• 社外秘コードを扱う企業が注意すべきセキュリティ要件
• Serena など類似MCPとの使い分け

想定読者

Claude Code や Cursor のコンテキスト枯渇に悩んでいるエンジニア、モノレポでコード横断検索を効率化したいチーム、社外秘コードのままAIコーディング支援を導入したい情報システム担当者。

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

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

公式が強調しているポイントは次の3つです。

• ハイブリッド検索：BM25（キーワード）と密ベクトル（意味）を組み合わせた検索
• AST ベースのコード分割：関数・クラス単位で意味のあるチャンクに切って埋め込む
• 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 経由で Claude Code などに返す

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

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

出典: zilliztech/claude-context GitHub公式

できること

• 自然言語でのコード検索：「ユーザー認証のJWT検証をしている場所」のような意味ベース検索
• マルチプロジェクト対応：各コードベースは絶対パスをキーにして管理、複数リポジトリを混在させても衝突しない
• 大規模リポジトリのインクリメンタル更新：Merkle Tree による差分検出で再インデックスが高速
• 主要プログラミング言語の AST 対応：TypeScript / JavaScript / Python / Java / C++ / C# / Go / Rust / PHP / Ruby / Swift / Kotlin / Scala / Markdown ほか
• ローカル完結運用：Ollama（埋め込み）＋Milvus Standalone（ベクトルDB）で外部送信なしに運用可能

できない・不得意なこと

• リアルタイム同期：ファイル変更の即時反映はされず、二次ソースでは平均15秒程度の遅延とされる
• シンボル単位のジャンプ／参照元追跡：LSP ベースの機能は Serena などの別MCPが得意領域
• Node.js 24 での動作：執筆時点では Node.js 20.x〜23 系が推奨（24 未対応）
• ベクトルDB なしでの単独動作：Milvus またはZilliz Cloud が別途必要

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

出典: Zilliz 公式サイト

claude-context 本体は OSS（MIT ライセンス）で無料ですが、実運用では埋め込みAPI と ベクトルDB のコストが発生します。構成の組み合わせで総額が大きく変わるのが注意点です。

コスト感の目安

• 完全無料で運用したい → Ollama + Milvus Standalone（Docker）
• とりあえず試したい → OpenAI 埋め込み + Zilliz Cloud Free Tier（新規$100クレジットあり）
• チームで本番運用したい → OpenAI または VoyageAI 埋め込み + Zilliz Cloud Serverless

大規模モノレポ（10万行オーバー）では、初回インデックス時の埋め込みAPI 料金が一時的に膨らむ点に注意してください。Zilliz Cloud 側のストレージ料金は毎月の継続コストとなるので、長期契約の前に Zilliz Cloud 公式料金ページ で最新単価を確認することを推奨します。

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

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

1. Node.js のバージョン：20.x〜23.x（24 は執筆時点で非対応）
2. 埋め込みAPIキー または Ollama のローカル環境
3. ベクトルDB の接続先（Zilliz Cloud なら URI とToken、ローカルなら Milvus の Docker起動）
4. MCPクライアント（Claude Code / Cursor / Windsurf / Gemini CLI / Codex CLI などのいずれか）

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

Claude Code の場合、MCP の設定は claude mcp add コマンド、または ~/.claude.json への直接記述で行います。ここでは OpenAI 埋め込み + Zilliz Cloud を使う最短構成を示します。

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

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

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

ステップ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 を再起動し、チャット内で次のように指示します。

/mcp
（claude-context が接続されていることを確認）

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

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

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

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

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

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

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

Codex CLI だけ TOML 形式で、上記 JSON の例は次のように書き換えます。

[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"

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

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

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

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

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

2. Milvus Standalone を Docker で起動

Milvus 公式の docker-compose.yml をダウンロードして起動します（Qiita の実践記事では v2.3.21 の安定版 docker-compose が紹介されています）。

mkdir milvus && cd milvus
curl -O https://github.com/milvus-io/milvus/releases/download/v2.3.21/milvus-standalone-docker-compose.yml
mv milvus-standalone-docker-compose.yml docker-compose.yml
docker compose up -d

デフォルトでは 19530 ポートを使いますが、WSL2 環境等で競合する場合は 19531 に付け替える、という対処事例が日本語のQiita記事で紹介されています。

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に一切送信されず、ローカルネットワーク内で完結します。受託開発や金融・医療系の社外秘コードを扱う現場ではこちらが現実的な選択肢です。

主要な環境変数一覧

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

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

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

claude-context を導入する際に必ず考慮すべきポイントです。

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

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

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

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

3. APIキーの管理

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

4. 業種別の推奨構成

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

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

選び方の目安

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

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

よくあるトラブルと対処

Q1. index_codebase がエラーで止まる

• Node.js のバージョンが 24 系になっていないか確認（20.x〜23.x で動作）
• Zilliz Cloud のトークンに改行や空白が混ざっていないか確認
• ローカルMilvus の場合、docker compose ps でコンテナが起動しているか確認

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

• 埋め込みモデルを text-embedding-3-small から text-embedding-3-large や voyage-code-3 に変える
• HYBRID_MODE=true が効いているか確認（キーワード一致が弱くなっている場合は BM25 側の寄与を確認）
• SPLITTER_TYPE=ast が効く言語か確認（対応外の言語では langchain にフォールバックされる）

Q3. インデックスが肥大化する

• CUSTOM_IGNORE_PATTERNS で node_modules/** dist/** **/*.min.js などを除外
• .gitignore 対象は自動で除外されるので、まず .gitignore を整える

Q4. ファイルを変更してもすぐ反映されない

これは仕様で、Merkle Tree による差分検出が非同期で走るため平均15秒程度の遅延があります。明示的に再インデックスしたい場合は clear_index → index_codebase の順で実行します。

Q5. Zilliz Cloud の無料枠を超えそう

• CUSTOM_IGNORE_PATTERNS で対象を絞る
• ローカル Milvus Standalone に移行する
• Serverless プラン（従量課金）に切り替える

こんな方におすすめ / 向いていない方

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

• Claude Code・Cursor・Codex CLI で大規模リポジトリ（目安：1万行以上）を扱っていてコンテキスト枯渇に悩んでいる
• 「どこで似た処理をしているか」を意味ベースで探したい
• モノレポを運用していて、AIエージェントに横断検索をさせたい
• 情報システム部門の方針でローカル完結構成を求められている（Ollama + Milvus で対応可能）

claude-context を無理に導入しなくてよい人

• 数千行以下の小規模プロジェクト：@ファイル名 や grep 相当で十分で、ベクトルDB の運用コストが見合わない
• シンボルジャンプ・参照元追跡が主用途：Serena のほうが適している
• リアルタイム反映が必須：数秒〜十数秒の遅延が許容できない用途には合わない
• Node.js 環境を用意できない／運用したくない：ランタイム管理がハードルなら別の手段を検討

よくある質問（FAQ）

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

二次ソース間で 5k〜8k 台と数字にぶれがあります。正確な最新値は GitHub 公式リポジトリ で確認してください。

Q. 公式に「40%のトークン削減」と書いてあるのは本当？

公式 README の評価セクションに記載されている内容で、第三者による再現検証は未確認です。自社環境での効果測定を推奨します。

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

はい、Zilliz 公式から VS Code Marketplace で提供されています。MCPサーバー単体と拡張機能版で提供機能に差があるかは執筆時点で未確認のため、公式ドキュメントでの確認を推奨します。

Q. GitHub Releases にバージョン情報がないけど最新版は？

執筆時点では GitHub Releases は作成されておらず、バージョン追跡は npm の @zilliz/claude-context-mcp を参照するのが確実です。npx @zilliz/claude-context-mcp@latest で最新版が自動取得されます。

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

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

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

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

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

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

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

関連記事

• Claude Code の全体像を知りたい方はまず「Claude Codeとは」
• 料金比較を踏まえて検討したい方は「Claude Code 料金」
• MCP という仕組みそのものを理解したい方は「MCPとは（Model Context Protocol）」
• Claude Code の設定ファイル運用について深掘りしたい方は「CLAUDE.md 書き方 ベストプラクティス」
• Claude Code とその他エディタの違いを確認したい方は「Cursor vs Claude Code 比較」
• コーディング支援AIを横断比較するなら「AIコーディングツール おすすめ 比較」