5 分钟搞定：在 Cloud Mac 上部署 CodeGraph MCP Server

大仓跑 codegraph init 时，笔记本风扇常先响起来。更省事的做法是：把 CodeGraph 与 MCP Server 部署在 Cloud Mac 上，你只用终端 SSH 进去执行几条命令；本地的 Claude Code、Cursor 继续写代码，不必在本机安装 CodeGraph、不必本地全量索引。

本文是一条可复制的最短路径：ssh root@zavcloud → brew install → codegraph init。若你已读过 CodeGraph 与 AI Coding Agent，本文只解决「放哪台机器、怎么五分钟上线」。

为什么把 CodeGraph MCP 放在 Cloud Mac？

CodeGraph 在仓库根目录生成 .codegraph/，首次 init -i 会长时间占用 CPU 与 NVMe。放在 ZavCloud Cloud Mac 上通常有这些好处：

• 与 xcodebuild、GitHub Actions Runner 同一台原生 macOS，图谱版本与构建环境一致；
• 开发者只需 SSH，无需在 Windows / Linux 本机折腾 macOS 专用依赖；
• 常驻节点可夜间增量索引，白天本地 Agent 只读图谱。

开始前准备

• 已开通 Cloud Mac（控制台可看到公网 IP 或 SSH 主机名）；
• 本机终端（Windows 可用 PowerShell / WSL，macOS / Linux 自带 ssh）；
• 代码已在云端 clone（或随后 git clone 到实例）；
• 可选：本机已装 Claude Code 或 Cursor（用于步骤 4 验证 MCP）。

步骤 1：SSH 登录 Cloud Mac

在控制台复制实例地址后，用 root（或面板提供的用户名）登录。示例：

# 示例：将 zavcloud 换成你的实例 IP 或分配域名
ssh root@zavcloud

# 若使用密钥（推荐）
ssh -i ~/.ssh/id_ed25519 root@203.0.113.10

首次登录若提示信任指纹，输入 yes。登录成功后提示符应显示云端 macOS 主机名——后续所有安装都在这台机器上完成，不是你的笔记本。

步骤 2：brew install CodeGraph

ZavCloud Cloud Mac 为原生 macOS，通常已带 Homebrew。用 brew 安装 Node 与 CodeGraph CLI（官方包名 @colbymchenry/codegraph）：

# 确认 Homebrew 可用
brew --version

# 安装 Node（若尚未安装）
brew install node

# 安装 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（建索引）

进入要交给 AI Agent 的仓库根目录，初始化并全量索引（大仓可加 -i）：

cd ~/workspace/your-monorepo
git pull

# 初始化 + 索引（首次可能 10–40 分钟，视仓库大小）
codegraph init -i

# 确认数据库已生成
codegraph status
ls -la .codegraph/

索引期间建议用 screen 或 tmux 防止 SSH 断开中断任务。完成后 .codegraph/codegraph.db 留在 Cloud Mac 磁盘上——本地机器无需拷贝整库，除非你有离线备份需求。

步骤 4：部署 MCP Server（Claude Code / Cursor）

在 Cloud Mac 上写入 MCP 配置（stdio 模式，命令为 codegraph serve --mcp）：

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

# 手动启动 MCP（调试时可前台运行）
codegraph serve --mcp

本地无需重复 install。 两种常见接法：

• 在 Cloud Mac 上直接跑 Claude Code / Cursor Remote（SSH + 远程开发）：MCP 读的是同一台机上的 .codegraph，零额外配置；
• 本机 Agent + 云端图谱：通过 SSH 将 codegraph serve --mcp 暴露给本机（团队常用 ssh -L 或内网固定 IP），本机 MCP 配置指向转发端口即可——仍不必在本机执行 codegraph init。

验证：5 分钟检查清单

常见问题与实战排错

下面按真实工单里出现频率排序：每条都给出「先确认什么 → 再执行什么命令 → 怎样算修好」。默认你已通过 SSH 登录 Cloud Mac，且仓库已 git clone 到实例磁盘（例如 ~/workspace/your-repo）。

SSH 连不上：ssh root@zavcloud 一直超时或 Permission denied

现象：Connection timed out、Permission denied (publickey)，或卡在 Are you sure you want to continue connecting 后失败。

处理步骤：

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 通常默认密钥登录，在面板重置 SSH 密钥或先用 VNC 登录，在「系统设置 → 共享」确认「远程登录」已打开。
4. 公司网络封 22 端口：换手机热点试一次；或向运维申请 IP 白名单（ZavCloud 独享实例带静态 IPv4，便于登记）。

修好标准：能稳定进入 shell，且 uname -a 显示 Darwin（macOS），而不是 Linux 容器。

brew install 或 codegraph 提示 command not found

现象：执行 brew install node 报 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 装 CodeGraph（不依赖 brew）。
2. 全局 npm 二进制不在 PATH：
   Cloud Mac

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

   把 export PATH=... 写入 ~/.zshrc，避免下次 SSH 又丢失。
3. 仍失败时，在 Cloud Mac 上一条命令安装（与 brew 无关）：
   备选

   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 显示未索引或数据库损坏。

处理步骤：

1. 以后一律在 tmux 里跑索引（断线任务继续）：
   Cloud Mac · 推荐

   brew install tmux
   tmux new -s codegraph
   cd ~/workspace/your-repo && codegraph init -i
   # 断线后重连 SSH，再执行：
   tmux attach -t codegraph

2. 看磁盘是否满（索引会写出数百 MB 的 .codegraph/）：

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

   空间不足时清理 DerivedData、旧 node_modules，或扩容磁盘后再跑。
3. 怀疑库损坏：在仓库根备份后删除 .codegraph/，重新 codegraph init -i（不要边跑边删）。
4. monorepo 可先排除巨型目录（按项目 .codegraphignore 或官方文档配置），减少首次索引时间；排除过多会导致 impact 漏文件，需权衡。

修好标准：codegraph status 显示已索引文件数 > 0，且 ls .codegraph/codegraph.db 存在。

Claude Code / Cursor 里看不到 CodeGraph，Agent 还是只会 Grep

现象：MCP 列表没有 codegraph；或对话里从不调用 codegraph_impact，改接口仍漏文件。

处理步骤：

1. 在 Cloud Mac（已 init 的同一用户下）重写 MCP 配置：

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

   应能看到 "command": "codegraph" 与 "args": ["serve", "--mcp"]。
2. 完全退出 Claude Code / Cursor 再打开（仅关窗口不算）。macOS 可从菜单栏退出；Windows 结束托盘进程。
3. 若你在本机跑 Claude Code、图谱在云端：本机 MCP 必须能执行到云端的 codegraph。常见做法是用 SSH 包装（示例，按你的 IP 改）：
   本机 ~/.claude.json 片段（示意）

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

   先在本机终端手动跑一遍 ssh root@YOUR_IP codegraph serve --mcp，能挂住不报错再交给 Agent。
4. Claude Code 若提示 MCP 工具需批准：在设置里对 mcp__codegraph__* 允许，或在 CLAUDE.md 写明「改公共 API 前必须调用 codegraph_impact」。

修好标准：新开一次对话，让 Agent「列出当前可用的 codegraph 相关工具」或「对某符号做 impact」——应返回文件路径列表，而不是空或纯 Grep。

codegraph impact 或 MCP 的 impact 返回空列表

现象：明明有调用方，codegraph impact "Foo.bar" 却是 0 条；Claude Code 据此以为「不用改别的文件」。

处理步骤：

1. 确认当前目录是已 init 的仓库根（含 .codegraph/）：

   pwd
   codegraph status

   在子目录执行时，部分版本需 cd 到根再查。
2. 符号名与语言一致：Swift 用 TypeName.method，TypeScript 注意 export 名与文件名不同；可先 codegraph search "Payment"（若 CLI 支持）或让 Agent 用 codegraph_callers 试拼写。
3. 索引过期：合并了 main 大改动后，在 Cloud Mac 上 git pull && codegraph init -i 或按官方文档做增量同步；否则图谱里仍是旧调用关系。
4. Generated / 第三方代码未编入索引：检查 .gitignore 是否把含调用的目录整包排除。

修好标准：对已知有调用方的符号，impact 至少返回 1 条路径；与手动 Grep 结果大致吻合（图谱应≥Grep，因含间接调用）。

一台 Cloud Mac 上要索引多个仓库，或 clone 到了错误目录

现象：在 A 仓库 init，却在 B 仓库开 Claude Code；或 ~/workspace 下多个项目只有一个有 .codegraph。

处理步骤：

• 每个仓库各自在根目录执行 codegraph init -i，各自生成 .codegraph/，不要共用父目录。
• 开 Agent 前 cd 到对应根目录，或 Remote-SSH 工作区直接打开该文件夹。
• 磁盘紧张时：只给「主 monorepo」建全量索引，小工具库用 CLI 临时 impact；大库索引可夜间用 cron + tmux 跑 git pull && codegraph init -i。

想在本地笔记本查图谱，但坚持不在本机跑 init

做法：索引仍在 Cloud Mac 生成，用 rsync 把仅 .codegraph/ 拉回本机（不传全仓源码亦可，若你本地已有 clone）：

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

拉回后在本机仓库根执行 codegraph status 验证；本机仍需 codegraph install 配 MCP，但不必本机再跑几十分钟的 init -i。团队可每晚从同一台 Cloud Mac 同步一份「黄金索引」到群成员。

索引时 Cloud Mac 很卡，和 Xcode 构建抢资源

处理建议：

• 用 caffeinate -dims 防止 macOS 睡眠中断索引（在 tmux 内执行）。
• 把 codegraph init -i 排在夜间或 CI 空闲窗口，与 xcodebuild 错峰；同一台机器见 Runner 手记。
• 活动监视器里若 codegraph 长期占满 CPU 属正常；若同时跑模拟器 + 索引，考虑临时加租一台 Cloud Mac 专做索引节点。

和「在本机装 CodeGraph」相比，我到底省了什么事？

功能上没有阉割版 Cloud Graph——差别在算力放哪。你省掉的是：在本机装 Node/Homebrew、全量解析时风扇噪音、以及「笔记本合盖索引暂停」。你仍需要：能 SSH、知道仓库在云端哪条路径、以及在 Agent 侧正确接上 MCP（本地 Remote 或 SSH 包装）。概念与漏改案例见 CodeGraph 与 AI Coding Agent；安装细节见 本地可视化全攻略。

• 概念— Claude Code 漏改与 CodeGraph
• CI 同机— 云端 Mac Runner
• 开通实例— Cloud Mac 租用