LoginSignup
2
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@sukimaengineer

Code Context をローカル Milvusで使う（Claude Code / OpenAI Codex CLI、WSL2対応版）

Last updated at Posted at 2025-08-31

※本記事は 2025-08-31 時点の情報に基づいています。

はじめに

「大きなリポジトリから、今ほしい断片だけ拾ってAIに渡したい」――そんなときに便利なのが Code Context です。これは MCP（Model Context Protocol）対応の “コード検索サーバ” で、ベクトルDBにインデックスしたコードから関連部分だけを抽出し、Claude Code や OpenAI Codex CLI に渡してくれます。
本記事では、アカウント不要・手元だけで完結する ローカル Milvus と組み合わせる手順に絞って解説します（Zilliz Cloud は使いません）。

  • 対象読者：WSL2（Ubuntu）で Claude Code や OpenAI Codex CLI（以下、Codex CLI） を使いたい方。社外にコードを出せない・オフライン環境で試したい方にもおすすめ。

  • この記事でできること

    1. Docker Compose で Milvus Standalone を起動
    2. Claude Code / Codex CLI から Code Context を MCP として接続
    3. 埋め込み（OpenAI / Gemini / Ollama 等）や基本の環境変数設定
    4. 最小ワンライナーやトラブルシューティング

  • 注意：Codex CLI の MCP 設定ファイルは config.toml と config.json の挙動がバージョンで異なる報告があります。手元の ~/.codex/ を必ず確認してください。

重要な注意事項

2025年8月31日時点で、Code Context は Node.js >= 20.0.0 かつ < 24.0.0 が要件です。Node 24 は非対応 なのでご注意ください。

つまり：

  • Node.js 20系（20.0.0以上）: ✅ 動作OK
  • Node.js 24系以上: ❌ 非対応

実際に使用する際は、以下のコマンドでバージョンを確認することをお勧めします：

node -v
# v20.x.x なら OK
# v24.x.x 以上なら、nvm等で20系に切り替えが必要

もしNode 24系を使っている場合は、nvmを使って簡単に切り替えられます：

nvm install 20
nvm use 20

この互換性の問題は、依存パッケージやNode.js 24での破壊的変更に起因する可能性があります。将来的には対応される可能性もあるので、最新情報はGitHubリポジトリでご確認ください。

1. Code Contextって何？

  • Code Context は、MCP対応のコード検索サーバです。数百万行規模でもセマンティック検索で関連コードだけを抽出し、AIへの提示コストを抑えます。
  • MCP と併用することで、Claude Code などから簡単に使えます。MCP の概要と Claude Code での追加方法は公式ドキュメントが分かりやすいです。

2. ローカル Milvus を Docker Compose で起動

Milvus の Standalone を Docker Compose で立ち上げます。要点は「Composeファイルを取得して docker compose up -d」。以下は例です（バージョンは適宜最新へ）。

# 1) 作業用ディレクトリへ
mkdir -p ~/milvus-local && cd ~/milvus-local

# 2) Composeファイルを取得（例：v2.3.21）
# ※最新版は https://github.com/milvus-io/milvus/releases で確認
wget https://github.com/milvus-io/milvus/releases/download/v2.3.21/milvus-standalone-docker-compose.yml -O docker-compose.yml

# 3) 起動
docker compose up -d
# ※ docker グループに所属していない場合は sudo が必要です
#   例）sudo usermod -aG docker $USER && newgrp docker

# 4) 状態確認
docker compose ps
  • 既定で gRPC ポート 19530 がホストに公開されます（Milvus への基本接続口）。
  • データは volumes/milvus などに永続化されます。
  • つながらない時は 19530 が他プロセスで使われていないか確認しましょう。

ポートの豆知識：Milvus は主に 19530（gRPC/デフォルト接続）を使います。9091 は管理系（メトリクス等）です。ブラウザで http://localhost:19530 にアクセスしてもページは出ません（gRPCだから）。

3. Claude Code から使う

3.1 Claude Code のインストール

npm i -g @anthropic-ai/claude-code
claude --help

3.2 Code Context（MCP）を追加（ローカル Milvus）

最小構成（OpenAI 埋め込み＋ローカル Milvus）です。

claude mcp add claude-context \
  -e OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxx \
  -e MILVUS_ADDRESS=http://127.0.0.1:19530 \
  -- npx @zilliz/claude-context-mcp@latest
# ※ @zilliz/code-context-mcp@latest でもOK
  • 以後は claude を起動し、Index this codebase → クエリ（例：「Find functions that handle user authentication」）で横断検索できます。
  • OpenAI 以外（Gemini / Ollama / VoyageAI など）に切り替える場合は、EMBEDDING_PROVIDER や各プロバイダのキー／ホストを付け替えます。

4. Codex CLI から使う

Codex CLI は MCP をサポートしており、~/.codex/config.toml に mcp_servers を書く方式が README にあります。
ただし、一部バージョンで config.json が採用される例が報告されています。まずは ~/.codex/ の中身を確認してください。

# インストール
npm i -g @openai/codex
codex

# ~/.codex/config.toml（例）
[mcp_servers.claude-context]
command = "npx"
args = ["-y", "@zilliz/claude-context-mcp@latest"]
env = {
  OPENAI_API_KEY = "sk-xxxxxxxxxxxxxxxx",
  MILVUS_ADDRESS = "http://127.0.0.1:19530"
}

起動後に codex → help や config 周りを確認しつつ、TOML か JSON どちらが有効かを見極めると安心です。

5. よく使う環境変数（ローカル Milvus 版）

変数名 用途 例 備考
EMBEDDING_PROVIDER 埋め込みプロバイダ OpenAI / Gemini / Ollama / VoyageAI 省略時は OpenAI が既定の例が多いです。
OPENAI_API_KEY OpenAI 用APIキー sk-... OpenAI を使う場合は必須。
GEMINI_API_KEY Gemini 用APIキー （例）... EMBEDDING_PROVIDER=Gemini のとき。
OLLAMA_HOST Ollama のアドレス http://127.0.0.1:11434 ローカル埋め込みで使用。
EMBEDDING_MODEL 埋め込みモデル名 text-embedding-3-small など プロバイダで最適な型を選択。
MILVUS_ADDRESS Milvus の接続先 http://127.0.0.1:19530 ローカルはこれだけでOK（既定は認証なし）。
MILVUS_TOKEN 認証トークン （任意） ローカルで認証を有効化した場合のみ必要。

6. 最小ワンライナー集（WSL2想定）

6.1 Milvus 起動（Docker Compose）

mkdir -p ~/milvus-local && cd ~/milvus-local
# 最新版は https://github.com/milvus-io/milvus/releases を確認
wget https://github.com/milvus-io/milvus/releases/download/v2.3.21/milvus-standalone-docker-compose.yml -O docker-compose.yml
docker compose up -d
# ※ docker グループ未所属なら sudo が必要です（usermod -aG docker $USER && newgrp docker）

6.2 Claude Code：MCP 追加（OpenAI + ローカル Milvus）

npm i -g @anthropic-ai/claude-code
claude mcp add claude-context \
  -e OPENAI_API_KEY=sk-xxx \
  -e MILVUS_ADDRESS=http://127.0.0.1:19530 \
  -- npx @zilliz/claude-context-mcp@latest

6.3 埋め込みを Gemini / Ollama に切り替え

# Gemini
claude mcp add claude-context \
  -e EMBEDDING_PROVIDER=Gemini \
  -e GEMINI_API_KEY=xxxxxxxx \
  -e MILVUS_ADDRESS=http://127.0.0.1:19530 \
  -- npx @zilliz/claude-context-mcp@latest

# Ollama（ローカル埋め込み）
claude mcp add claude-context \
  -e EMBEDDING_PROVIDER=Ollama \
  -e EMBEDDING_MODEL=nomic-embed-text \
  -e OLLAMA_HOST=http://127.0.0.1:11434 \
  -e MILVUS_ADDRESS=http://127.0.0.1:19530 \
  -- npx @zilliz/claude-context-mcp@latest

7. データの永続化について

Milvus のデータは通常、Compose のボリューム（例：volumes/milvus）に保存されます。完全にリセットしたい場合は次の手順でクリーンにできます。

docker compose down
rm -rf volumes/
docker compose up -d

※ ボリュームを消すとデータは失われます。必要なら事前にバックアップを取ってください。

8. トラブルシューティング

  • Milvus に繋がらない

    • docker compose ps で milvus-standalone が running か確認。
    • ログは docker compose logs -f milvus-standalone。
    • nc -vz 127.0.0.1 19530 でポート疎通チェック。

  • 19530 ポートが既に使用中

    # 使用中のプロセスを確認
sudo lsof -i :19530
# または
sudo netstat -tlnp | grep 19530

    docker-compose.yml のポートを変更（例：19531）して再起動します。

    # ports:
#   - "19531:19530"

    その場合は接続先も

    export MILVUS_ADDRESS=http://127.0.0.1:19531

    に合わせます。

  • ブラウザで localhost:19530 を開いても何も出ない

    • ここは gRPC ポートです。HTTP では見えません。

  • Node のバージョンでエラー

    • Code Context は Node 20系（24未満） が要件です。20系へ切り替えましょう。

  • Codex CLI が MCP を読まない

    • ~/.codex/config.toml ではなく config.json が使われる例があります。~/.codex/ を確認して合う形式で設定を。

9. Attu（Web UI）を使いたい場合

Milvus をブラウザで眺めたいときに便利です。Compose にサービスを一つ足します（同じネットワーク上なので Milvus をサービス名で参照できます）。

# docker-compose.yml に追記
  attu:
    image: zilliz/attu:latest
    ports:
      - "8000:3000"
    environment:
      - MILVUS_URL=milvus-standalone:19530
    depends_on:
      - milvus-standalone

起動後、ブラウザで http://localhost:8000 にアクセス。
（Docker からホストの Milvus へ繋ぐ場合は localhost が通らないことがあるので、ネットワーク設計に応じて host.docker.internal などを使ってください。）

10. ローカル Milvus と Zilliz Cloud の比較

どちらも検索のコア機能（IVF / HNSW / PQ、メタデータフィルタ、ハイブリッド検索）自体は同等です。違いが出やすいのは“運用まわり（スケール、管理、可観測性、接続、SLAなど）”。用途に合わせて選ぶのがおすすめです。

項目 ローカル Milvus Zilliz Cloud
コア検索機能 同等（OSS の Milvus 機能をそのまま利用） 同等（Milvus をマネージド提供）
スケール / 可用性 自前設計（ノード増設・冗長化・監視が必要） マネージド（自動スケールや高可用性はプラン依存）
管理UI / メトリクス 自前（Attu、Grafana/Prometheus 等） コンソールあり（メトリクス/アラート等・プラン依存）
バックアップ / リストア 自前（Milvus Backup、スナップショット設計） コンソールやマネージド機能あり（プラン依存）
セキュリティ（TLS/認証/RBAC） 有効化・運用は自分で設定 既定の機能や設定UIあり（プラン依存）
監査ログ / SSO 原則自前で実装・連携 提供あり（プラン依存）
ネットワーク接続 ローカル/オンプレ/閉域・オフライン可 パブリック接続＋PrivateLink/PSC 等（プラン依存）
SLA / サポート なし（自社で可用性担保） あり（プラン依存）
コスト感 インフラ費＋運用工数（電気代＋人的コスト） サービス課金（運用負担は小さめ）
セットアップ時間 多少手間（Docker Compose 等） 早い（サインアップ→クラスタ作成）
データ所在地の制御 完全ローカルで制御しやすい クラウドリージョン選択で管理
オフライン利用 可能 原則不可
アップグレード / パッチ 自分で適用 マネージド側で適用
向いている用途 PoC/手元完結/機密データ/オフライン要件 本番運用/スケール/監査・SLA要件

どっちを選ぶ？ 簡単な目安

  • コードを外に出したくない・閉域/オフライン要件がある → ローカル Milvus
  • 手早く試す・運用の手間を減らしたい → Zilliz Cloud
  • 中長期で本番運用し、SLA や監査ログが必要 → Zilliz Cloud（適切なプラン）
  • PoC〜小規模本番でコストと自由度を取りたい → ローカル Milvus（将来 Cloud へ移行も容易）

補足：どちらを選んでも、Code Context 側の使い方はほぼ同じです。切り替えは主に接続先と認証（MILVUS_ADDRESS／MILVUS_TOKEN など）の設定差だけです。

11. まとめ

  • ローカル Milvus ならアカウント不要・手元完結で Code Context を試せます。
  • Milvus は Docker Compose で簡単起動、接続は MILVUS_ADDRESS=http://127.0.0.1:19530 が基本。
  • Claude Code／Codex CLI からは MCP として npx @zilliz/claude-context-mcp@latest を呼び出せばOK。Node は 20系（24未満） を使いましょう。

FAQ

用語の整理（LLM／Embedding／ベクトルDB）

まずは役割分担をざっくり整理します。

  • LLM（大規模言語モデル）：最終的な回答を出す“頭脳”。Claude Code や Codex CLI から呼び出されます。

  • Embedding（埋め込み）：テキストやコードを“数値ベクトル”に変換する処理。

    • 例：OpenAI Embeddings / Gemini / VoyageAI / Ollama（ローカル） など

  • Vector DB（ベクトルDB）：ベクトルを保存し、類似検索を行う“検索ストレージ”。

    • 例：Milvus（本記事はローカル運用）

  • Code Context（MCP）：上記をつないで、**関連コード断片（Top-K）**を LLM に渡す“オーケストレーター”。

全体の動作フロー

よくある誤解ポイント

  • 「Milvus は ChatGPT の API を使って動く」→ いいえ。
    Milvus は ChatGPT（対話用）API には依存しません。Milvusの役割はベクトルの保存・類似検索です。
  • ChatGPT の月額（Plus/Team 等）＝ API キー？ → いいえ。
    ChatGPT のサブスクと OpenAI API は別サービスです。Embedding を OpenAIで生成する場合は、OpenAI API Key（sk-...） が必要です。
    Ollama を使えば 完全ローカル生成で API すら不要です。

Q: Embedding の指示は Code Context が行うのですか？ その場合、行うタイミングは？
A: はい、Code Context（MCPサーバ）が担当します。 タイミングは大きく分けて (1) インデックス作成時 と (2) 検索時 の 2 つです。

  • (1) インデックス作成時（初回・再インデックス）
    リポジトリを走査 → チャンク分割 → 各チャンクの埋め込みを生成 → Milvus に保存（アップサート／インデックス化）までを Code Context が自動実行します。
    再インデックスでは 変更差分のみ再埋め込み（インクリメンタル）なので高速です。
    目安となる操作：Index this codebase（または index_codebase ツール）、進捗確認：get_indexing_status。

  • (2) 検索時（自然言語の質問を投げた瞬間）
    ユーザーの質問テキストを その場で埋め込みに変換 → Milvus に保存済みのコード埋め込みと照合（必要に応じてハイブリッド検索：BM25 + ベクトル）→ Top-K の関連断片を返します。
    目安となる操作：Find …（または search_code ツール）。

  • 誰が埋め込みプロバイダを呼ぶ？
    Code Context が直接呼び出します。 EMBEDDING_PROVIDER／OPENAI_API_KEY／GEMINI_API_KEY／OLLAMA_HOST などの環境変数で、OpenAI / Gemini / VoyageAI / Ollama（ローカル） を切り替え可能です。

まとめ：コード側の埋め込みは「インデックス時」に作成し、質問の埋め込みは「検索時」に生成。更新は差分再埋め込みで効率化されます。

Q: 埋め込み生成しない時もあるのですか？
A: あります。 正確には「新しく埋め込みを作らない」ケースがいくつかあります。

  • (1) 再インデックス不要なとき
    すでにコードベースをインデックス済みで、ファイル更新がない場合は既存ベクトルを再利用します（新規生成なし）。
    再インデックスしても差分のみ再埋め込みなので、変更のないファイルは作りません。

  • (2) 検索だけ行うとき
    通常、検索時は質問テキストだけを埋め込みに変換します。
    逆に「特定ファイルを開く」「ログを表示する」など検索を伴わない操作では埋め込みを作りません。

  • (3) バックアップ／移行からの復元
    既に作成済みのベクトルを Milvus にリストアした場合、そのまま再利用できます（再生成不要）。

  • (4)（環境依存）ベクトルを使わない検索モード
    設定やバージョンによっては、BM25 などの語彙ベースのみで検索する構成・重み付けが可能な場合があります。
    この場合は新規の埋め込みを作らずに検索します（※可否は環境依存）。

  • (5) 設定不備やエラー時
    EMBEDDING_PROVIDER や API キー未設定、レート制限などで埋め込み生成に失敗した場合、
    実装によってはエラーで止まる／語彙ベースのみで続行等の挙動になります（ログで要確認）。

（参考）必ず／通常作るタイミング

  • 初回インデックス：コード側の埋め込みを生成。
  • 検索時：ユーザーの質問テキストを埋め込みに変換（同一質問のキャッシュ有無はバージョン依存）。

　動作確認のヒント

  • インデックス状態：get_indexing_status（UI の「Index this codebase」進捗でも可）
  • 設定確認：claude mcp get claude-context（環境変数・コマンドを点検）
  • ログ：生成失敗やフォールバックはログに痕跡が出ます

Q: ローカル Milvus でも十分実用的ですか？
A: はい。類似検索の検証や社内限定の運用に向いています。将来クラウド移行する場合も、基本は MILVUS_ADDRESS／MILVUS_TOKEN の切り替えで対応できます。

Q: 19530 以外のポートは？
A: 通常は 19530（gRPC、デフォルト接続）だけ意識すればOKです。9091 は管理系ポートです。

Q: Milvus の状態をGUIで見たい
A: 本文の 「Attu（Web UI）」 節を参照してください。Docker ネットワーク越しの接続先指定に注意すれば、簡単に可視化できます。

Q: ChatGPT Plus/Team を契約していれば、API Key は不要ですか？
A: いいえ、別物です。 ChatGPT の月額サブスク（Plus/Team/Enterprise）はブラウザ/アプリでの利用向け、OpenAI API は従量課金の開発者向けサービスで、API Key（sk-...）は別途発行が必要です。API Key は OpenAI Platform の「API keys」ページから作成します。料金はAPI の料金表に従って課金されます（埋め込みの一例として text-embedding-3-small が $0.02 / 1M tokens といった価格帯の発表がありました。必ず最新の Pricing をご確認ください）。

Q: API料金を避けたい・極力抑えたいのですが？
A: Ollama を使ってローカルで埋め込みを計算すれば API 料金はかかりません（そのぶんマシンスペック依存になります）。本文の「最小ワンライナー集」の Ollama 例をどうぞ。

参考リンク（UTM なし）

以上

2
1
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
2
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?