codebase-memory-mcp 設定チュートリアル｜大型コード向け実践手順

「AIにリポジトリを渡せば、次の会話でもプロジェクト全体を覚えている」と考えると、codebase-memory-mcpの設定途中でつまずきやすくなります。通常の会話履歴は、ファイルの関係や呼び出し経路を永続的な索引として保持する仕組みではないためです。

実際には、インストールできたことと、AIがコードベース記憶を使って回答していることは別問題です。この記事では、導入から索引、Claude Code接続、利用確認、更新、障害対応までを一つの作業手順として整理します。

コードを読み込ませるだけでは、なぜ足りないのでしょうか？

通常のAIコーディングでは、質問のたびに関連ファイルを検索して文脈へ追加します。しかし大型プロジェクトになると、次のような制限が出てきます。

• 同じ定義や設定ファイルを何度も読み込み、コンテキストを消費する
• 関数の呼び出し元、継承関係、モジュール間の依存を推測に頼りやすい
• 会話を新しくすると、前回確認した設計上の前提が失われる
• ブランチ変更後に、AIが古いコード関係を参照する可能性がある
• リポジトリ全体をそのまま許可すると、秘密情報や生成物まで対象になる

MCPは、AIアプリケーションが外部のデータやツールへ標準化された方法で接続するためのオープンな仕組みです。codebase-memory-mcpは、そのMCP接続を通じてコードベースを構造化し、AIクライアントから関係検索を利用できるようにします。(Anthropic公式MCPドキュメント)

どのプロジェクトに向いていますか？

すべてのリポジトリにコードベース記憶が必要なわけではありません。小規模な個人用スクリプトなら、通常の全文検索だけで十分な場合もあります。

この判断で重要なのは、ファイルの内容を検索したいのか、コード同士の関係を追跡したいのかです。大型コードベースでAIの文脈を最適化するなら、単語検索だけでなく、定義、呼び出し、依存関係を確認できる構造索引が候補になります。

インストール前に確認することは？

まず、作業対象をプロジェクトのルートディレクトリに限定します。node_modules、ビルド成果物、ログ、秘密鍵、環境変数ファイルまで索引対象にすると、処理量と情報漏えいリスクが増えます。

macOSでは、実行ファイルの種類、ターミナルのPATH、対象ディレクトリの読み取り権限を確認してください。プロジェクトのリポジトリで公開されている導入手順では、macOSとLinux向けにインストールスクリプトが案内されています。実行前にスクリプトの内容と取得元を確認し、チームのセキュリティ方針に合わない場合はリリース配布物を手動導入する方法を選びます。

codebase-memory-mcpの公式リポジトリと導入手順

注意：curlで取得したスクリプトをそのまま実行する前に、対象リポジトリ、通信先、保存先、実行権限を確認してください。社内プロジェクトでは、最初から本番コード全体を対象にせず、検証用の複製リポジトリで試す方が安全です。

初回索引を作る手順は？

ここからは、MCPによるコードベース記憶をどのように使うかという疑問を、実際の作業手順に置き換えて説明します。

1. 作業用ディレクトリを決める

cd ~/Projects/sample-app
pwd
git status

pwdで想定したプロジェクトルートにいること、git statusで意図しない変更がないことを確認します。サブディレクトリで起動すると、一部の依存関係だけが登録されることがあります。

2. プログラムを導入する

公式手順の例では、macOSとLinuxで次の形式が案内されています。

curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash

導入後、コマンドがPATHから見えるか確認します。

command -v codebase-memory-mcp
codebase-memory-mcp --help

実際の最新版や配布形式は変わる可能性があるため、固定したバージョンをチームで運用する場合は、公式リリースの検証済みファイルを使ってください。公開リリースには、macOS向けのアーキテクチャ別配布物とチェックサム情報が掲載されています。(公式リリース一覧)

3. コードベースを索引する

MCPクライアントを起動する前に、プロジェクトルートが正しいかを確認します。初回は、ソースコードの量、除外対象、利用する言語によって処理時間とメモリ使用量が変わります。

codebase-memory-mcp

その後、接続したAIクライアントから、次のように依頼します。

このプロジェクトを索引してください。
対象は現在のリポジトリだけに限定し、生成物と秘密情報は除外してください。

公式リポジトリでは、初回接続時の自動索引を有効にする設定例として、次のコマンドが示されています。

codebase-memory-mcp config set auto_index true

ただし、複数プロジェクトを同じ環境で扱う場合は、自動索引を一括で有効にする前に対象パスを確認してください。公開情報では、自動索引の対象ファイル数上限を設定する例もあります。(公式リポジトリの設定例)

4. 索引結果を確認する

索引完了後、いきなり大規模な修正を依頼してはいけません。まず、存在するシンボルや依存関係が正しく登録されているかを確認します。

このプロジェクトの認証処理の入口を探してください。
その関数の呼び出し元を上流から3段階確認し、関連する設定ファイルも示してください。

ファイル名だけでなく、関数名、呼び出し方向、関連モジュールが返るかを見ます。結果が単なるファイル一覧だけなら、索引が未完了か、AIがMCPツールを呼ばずに通常検索を使っている可能性があります。

5. 索引対象を最小化する

最初からリポジトリ全体を登録するより、アプリケーション本体、共有ライブラリ、テストの順で範囲を広げる方が原因を特定しやすくなります。

特に次のファイルは、通常は除外候補です。

.env
.env.*
*.pem
*.key
node_modules/
build/
dist/
coverage/
tmp/

除外方法はプロジェクトの設定やリリース版によって異なるため、利用中の公式READMEで確認してください。除外設定が効いているかは、秘密情報を含まないテスト用ファイルを置き、検索結果に出ないことを確認すると安全です。

Claude Codeに接続するには？

Claude Codeへcodebase-memory-mcpを接続する場合、まずクライアント自体が正常に動作することを確認します。公式ドキュメントでは、インストール後にプロジェクトへ移動して起動し、claude doctorで環境を診断する手順が案内されています。(Claude Code公式ガイド)

Claude CodeのMCP設定は、コマンドラインから管理できます。ローカル設定、プロジェクト共有設定、ユーザー全体の設定を分けられるため、最初は現在のプロジェクトだけで試すのが無難です。(Claude CodeのMCP設定)

claude mcp add codebase-memory \
  --scope local \
  -- codebase-memory-mcp

登録後は、次のコマンドで状態を確認します。

claude mcp list
claude mcp get codebase-memory

Claude Codeを再起動し、プロジェクトルートから次のように依頼します。

コードベース記憶を使って、注文処理の呼び出し経路を確認してください。
通常の全文検索だけで回答せず、利用したMCPツール名と対象プロジェクトを示してください。

チームで共有する設定にする場合は、プロジェクト設定を選択できます。ただし、実行ファイルのパスがメンバーごとに異なると接続に失敗します。固定パス、環境変数、導入手順をREADMEに残し、個人環境だけに依存しない形にしてください。

AIが本当にコードベース記憶を使ったか、どう検証しますか？

接続済みと表示されても、AIが毎回MCPツールを呼ぶとは限りません。次の3種類のテストを順番に行うと、接続だけの状態と実利用の状態を分けられます。

1. 構造説明テスト
   「このサービスの入口からデータベース書き込みまでの経路を説明してください」と依頼します。複数ファイルの関係が具体的に示されるか確認します。

2. 呼び出し元テスト
   特定の関数について、呼び出し元と呼び出し先を分けて質問します。単なる文字列一致ではなく、関係の方向が説明されるかを見ます。

3. 影響分析テスト
   共有インターフェースを変更した場合の影響範囲を尋ねます。テスト、実装、設定、別サービスまで区別できるかを確認します。

回答に「見つかりません」とだけ出る場合は、対象パス、索引状態、言語解析の対応状況を確認します。反対に、実在しない関数や古いファイルを断定する場合は、現在のブランチと索引の世代が一致していない可能性があります。

索引を更新するタイミングは？

コードが変わった後も、古い関係情報が残っていれば、AIはもっともらしい誤回答を返します。更新方法は、変更量とブランチ運用によって分けてください。

• 小さな変更：変更検知や増分更新を利用する
• 大規模なリファクタリング：索引を再構築する
• ブランチ切り替え後：現在のコミットと索引の世代を確認する
• 依存関係の大幅変更後：モジュール関係を再確認する
• 生成コードを更新した後：生成元と生成物の扱いを決める

公式リポジトリでは、既存プロジェクトを監視対象にしてGitの変更を検知する仕組みや、共有用の圧縮グラフ成果物に関する説明があります。ただし、共有成果物をコミットするかどうかは、リポジトリ容量、機密性、更新頻度を見て判断してください。(公式README)

経験上、索引の正しさを「更新が成功した」というメッセージだけで判断するのは危険です。直前に変更した関数を指定し、呼び出し元と変更影響を再検索して、結果が現在のブランチと一致することまで確認してください。

索引に失敗したときは、どこから調べますか？

MCPの索引失敗を調べるときは、次の順番で切り分けると時間を浪費しにくくなります。

パスが違う

pwd、git rev-parse --show-toplevel、MCP設定内の実行ディレクトリを比較します。相対パスは起動場所によって変わるため、チーム運用では絶対パスまたは明示的な環境変数を検討します。

権限がない

対象ディレクトリの読み取り権限、索引データの保存先、既存データベースの所有者を確認します。別のユーザーや管理者権限で一度起動すると、後から通常ユーザーで更新できないことがあります。

クライアントを再起動していない

MCP設定を変更した後は、AIクライアントを完全に終了して再起動します。claude mcp listで登録されていても、実行中のセッションへ反映されているとは限りません。

リポジトリが大きすぎる

巨大なモノレポでは、最初に対象範囲を限定します。生成物や依存パッケージを除外し、サービス単位で索引を作ってから関連リポジトリへ広げます。

ツールが呼ばれていない

「MCPを使って」と依頼しても、AIが通常のファイル検索で回答する場合があります。回答にツール名、対象パス、検索した関係を明示させ、必要なら詳細ログやクライアントのMCP状態画面を確認します。

権限を広げすぎている

MCPサーバーにリポジトリ全体の読み取り権限を与えると、秘密情報まで対象になる可能性があります。プロジェクト単位の設定を基本にし、不要なディレクトリを除外してください。

ZilCloudのクラウドMacで試すときの確認項目

クラウドMac開発環境で導入する場合、ローカル端末とは別に、接続の継続性とプロジェクト隔離を確認する必要があります。ZilCloudで検証する際は、次の項目を実測して記録してください。

現時点で未計測の項目は、典型値や推測で埋めないでください。リポジトリの公開ベンチマークは特定条件下のプロジェクトとハードウェアに依存するため、ZilCloud上の実際の結果とは分けて扱う必要があります。(公式リポジトリの説明)

2026年のチーム運用は、どの順番が安全ですか？

最初から全社標準にするより、次の段階で導入すると失敗の範囲を抑えられます。

1. 読み取り専用の検証用リポジトリを選ぶ
2. 除外対象と機密情報の扱いを決める
3. 1つのMCPクライアントで接続する
4. 構造説明、呼び出し経路、影響分析の3テストを実施する
5. ブランチ切り替え後の更新手順を決める
6. 索引失敗時のログ、担当者、復旧方法を文書化する
7. 効果が確認できたプロジェクトだけ、チーム共有設定へ広げる

ローカルPCだけで試す方法は手軽ですが、端末ごとにPATH、権限、作業場所、スリープ状態が異なり、再現性を保ちにくいという弱点があります。共有サーバー方式も、プロジェクト間の権限分離、接続遅延、常時稼働費用の管理が課題になります。

その点、ZilCloudのクラウドMacなら、Mac向け開発ツールと対象リポジトリを分離した環境で、インストール、索引、再接続、複数プロジェクトの隔離を同じ手順で繰り返し検証できます。まずはZilCloudのクラウドMac環境で実コードを使って確認し、必要な期間だけ利用したい場合は料金プランと照らし合わせながら、チームのMCP運用に組み込めるか判断するのが現実的です。

関連記事

• AI開発環境をクラウドMacへ移行する方法
• AIエージェントを常時稼働させるクラウドMac基盤の構築
• AIコーディング環境の比較とコード索引の活用法