Cloud Macに CodeGraph MCP を導入 — 5分の手順

巨大リポで codegraph init すると、まずノートPCのファンが回ります。CodeGraph と MCP を Cloud Mac に載せる方が早い — SSH で数コマンド；ローカルの Claude Code / Cursor はそのまま、ローカル CLI も全量索引も不要。

最短コピペ：ssh root@zavcloud → brew install → codegraph init。CodeGraph と AI コーディングを読済みなら、本文は「どのマシンで5分起動か」だけ。

なぜ Cloud Mac で CodeGraph MCP？

CodeGraph はリポ根に .codegraph/；初回 init -i は CPU/NVMe 集中。ZavCloud Cloud Mac なら：

• xcodebuild や GitHub Actions Runner と同一 macOS でグラフ版が一致；
• 開発者は SSH だけ — Windows/Linux に macOS ツールチェーン不要；
• 常駐ノードで夜間索引、昼は読み取り専用クエリ。

事前準備

• Cloud Mac 開通（コンソールに IP/SSH ホスト名）；
• ローカル端末；
• コードをクラウドに clone；
• 任意：Claude Code / Cursor で MCP 確認。

手順1：Cloud Mac に SSH

コンソールのアドレスをコピーし root でログイン。例：

# Example: replace zavcloud with your instance IP or hostname
ssh root@zavcloud

# Key-based login (recommended)
ssh -i ~/.ssh/id_ed25519 root@203.0.113.10

初回は yes でフィンガープリント承認。プロンプトはリモート macOS — 以降はノートPCではない。

手順2：brew install CodeGraph

ZavCloud Cloud Mac はネイティブ macOS + Homebrew。Node と CLI をインストール：

# Confirm Homebrew
brew --version

# Install Node if needed
brew install node

# Install CodeGraph CLI
npm install -g @colbymchenry/codegraph
codegraph --version

公式インストーラも同一 SSH セッションで可：

curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh

手順3：codegraph init（索引）

Agent に渡すリポ根で初期化＋全量索引（大規模は -i）：

cd ~/workspace/your-monorepo
git pull

# Init + index (first run may take 10–40 min)
codegraph init -i

# Confirm database
codegraph status
ls -la .codegraph/

tmux 推奨。完了後 .codegraph/codegraph.db は Cloud Mac 上 — 丸ごとローカルコピー不要。

手順4：MCP デプロイ

Cloud Mac で MCP 設定（codegraph serve --mcp）：

codegraph install --target=claude,cursor --yes

# Foreground MCP (debug)
codegraph serve --mcp

ローカルに二重 install 不要。 典型パターン：

• Cloud Mac 上で Remote 開発：同一 .codegraph — 追加設定ゼロ；
• ローカル Agent + クラウドグラフ：ssh -L 等 — ローカル init 仍不要。

検証：5分チェックリスト

FAQ・実践トラブルシュート

サポート頻度順。各項目：確認 → コマンド → 完了条件。Cloud Mac に SSH 済み、~/workspace/your-repo に clone 済み想定。

SSH失敗：ssh root@zavcloud がタイムアウト／Permission denied

症状: Connection timed out、Permission denied (publickey)、またはフィンガープリント後に失敗。

対処手順:

1. zavcloud をコンソールのパブリックIPに置き換え（例 ssh root@203.0.113.10）。名前解決できないとタイムアウトが最多。
2. 鍵の権限を確認：
   ローカル

   chmod 600 ~/.ssh/id_ed25519
   ssh -v -i ~/.ssh/id_ed25519 root@YOUR_IP

   -v で Offering public key か no mutual signature か——後者は鍵未登録のことが多い。
3. IP到達可だがパスワード拒否：Cloud Macは鍵認証が基本。パネルで鍵リセット、またはVNCで「リモートログイン」を確認。
4. 社内で22番遮断：テザリングで一度試す；専有インスタンスの固定IPv4はホワイトリスト登録に便利。

完了の目安: シェルに安定接続し uname -a が Darwin（macOS）を示す。

brew install や codegraph が command not found

症状: brew: command not found、または npm i -g 成功後 codegraph --version が見つからない。

対処手順:

1. Homebrewパス（Apple Silicon）：
   Cloud Mac

   test -x /opt/homebrew/bin/brew && eval "$(/opt/homebrew/bin/brew shellenv)"
   brew --version

   brewが無ければ Homebrew を入れるか install.sh を使用。
2. npmグローバルbinをPATHへ：
   Cloud Mac

   npm config get prefix
   export PATH="$(npm config get prefix)/bin:$PATH"
   which codegraph
   codegraph --version

   export PATH=... を ~/.zshrc に永続化。
3. フォールバック：
   代替

   curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh
   exec $SHELL -l

完了の目安: which codegraph がパスを返し codegraph --version が表示される。

codegraph init -i が止まる／SSH切断で索引が壊れる

症状: 長時間出力なし；SSH切断後 codegraph status が未索引またはDB破損。

対処手順:

1. 索引は必ず tmux 内：
   Cloud Mac · 推奨

   brew install tmux
   tmux new -s codegraph
   cd ~/workspace/your-repo && codegraph init -i
   # After reconnect:
   tmux attach -t codegraph

2. ディスク容量確認：

   df -h .
   du -sh .codegraph 2>/dev/null

3. DB破損疑い：リポジトリ根で .codegraph/ をバックアップ後削除し codegraph init -i を再実行（実行中は削除しない）。
4. 巨大monorepoは .codegraphignore で調整——除外しすぎると impact が漏れる。

完了の目安: codegraph status の索引ファイル数 > 0、.codegraph/codegraph.db が存在。

Claude Code / Cursor に CodeGraph が出ない

症状: MCP一覧に codegraph が無い；codegraph_impact を呼ばない。

対処手順:

1. Cloud MacでMCP再設定：

   codegraph install --target=claude,cursor --yes
   grep -A6 codegraph ~/.claude.json 2>/dev/null || cat ~/.claude.json

   "command": "codegraph" と serve --mcp を確認。
2. Claude Code / Cursor を完全終了して再起動（ウィンドウを閉じるだけでは不十分）。
3. ローカルAgent＋クラウドグラフ：
   ローカル ~/.claude.json

   {
     "mcpServers": {
       "codegraph": {
         "type": "stdio",
         "command": "ssh",
         "args": ["root@YOUR_IP", "codegraph", "serve", "--mcp"]
       }
     }
   }

   先に ssh root@YOUR_IP codegraph serve --mcp を手動テスト。
4. ツール承認が必要なら mcp__codegraph__* を許可、または CLAUDE.md で公開API変更前に impact 必須と明記。

完了の目安: 新規チャットで codegraph ツール一覧または impact がファイルパスを返す（空やGrepのみでない）。

codegraph impact が空リスト

症状: 呼び出し元があるのに codegraph impact "Foo.bar" が0件。

対処手順:

1. 索引済みリポジトリ根にいるか：

   pwd
   codegraph status

2. シンボル名を言語に合わせる（Swift: TypeName.method）。codegraph_callers で綴り確認。
3. 索引が古い：Cloud Mac で git pull && codegraph init -i。
4. .gitignore で呼び出し元ディレクトリが丸ごと除外されていないか確認。

完了の目安: 既知の参照があるシンボルで impact が1件以上；結果は手動grep以上（間接呼び出し含む）。

複数リポ／間違ったフォルダでAgent起動

症状: Aでinit、Bでコーディング；~/workspace の1つだけ .codegraph/ がある。

対処手順:

• 各リポジトリ根で個別に codegraph init -i。親ディレクトリ共有は不可。
• Agent前に正しい根へ cd、または Remote-SSH でそのフォルダを開く。
• ディスク逼迫時：メインmonorepoのみ全量索引；夜間 cron + tmux で更新。

完了の目安: Agentワークスペース根が .codegraph/codegraph.db を含むディレクトリと一致。

ローカルで索引せずグラフを参照したい

症状: ローカルMCPは欲しいが30分の init は避けたい。

対処手順:

1. 索引はCloud Mac；.codegraph/ のみ同期：
   ローカルで実行

   rsync -avz --progress root@YOUR_IP:~/workspace/your-repo/.codegraph/ ./your-repo/.codegraph/

2. ローカル根で codegraph status；MCP用に codegraph install——二度目の init -i は不要。

完了の目安: ローカル codegraph status OK、MCPが同期DBを参照。

チームは同一Cloud Macから夜間に「ゴールデン索引」をrsyncすることが多い。

索引中にCloud Macが重い／Xcodeと競合

症状: CPU張り付き；ビルドと索引が同一ホストで競合。

対処手順:

• tmux内で caffeinate -dims を実行しスリープ中断を防ぐ。
• codegraph init -i を夜間やオフピークに；xcodebuild とずらす——../openclaw-cloud-automation/openclaw-cloud-automation.html Runner参照。
• codegraph のフルCPUは正常；シミュレータ併用時は索引専用Cloud Macを追加検討。

完了の目安: 索引完了・DB健全；日中の開発/ビルドが実用可能。

ローカル install と比べて何が省ける？

機能は同じ — 計算場所だけ違う。ローカル Node/ファン/蓋閉じ中断を省略。SSH・パス・MCP 配線は必要。概念：CodeGraph と AI コーディング；詳細：大規模リポ CodeGraph ガイド（2026）。

• 概念— Claude Code 修正漏れ
• CI 同機— Cloud Mac Runner
• インスタンス— Cloud Mac プラン