How to Deploy CodeGraph MCP on Cloud Mac in 5 Minutes

Running codegraph init on a huge repo usually spins up your laptop fan first. The faster path: deploy CodeGraph and the MCP server on a Cloud Mac — SSH in, run a few commands; local Claude Code and Cursor keep coding with no local CodeGraph install and no full local index.

This is the shortest copy-paste path: ssh root@zavcloud → brew install → codegraph init. If you already read CodeGraph for AI coding agents, this article only answers which machine and how to go live in five minutes.

Why run CodeGraph MCP on Cloud Mac?

CodeGraph writes .codegraph/ at repo root; first init -i hammers CPU and NVMe. On a ZavCloud Cloud Mac teams usually get:

• Same native macOS as xcodebuild and your GitHub Actions runner — graph version matches build env;
• Developers only need SSH — no macOS toolchain on Windows/Linux laptops;
• Always-on node can index overnight; daytime agents read-only query the graph.

Before you start

• Active Cloud Mac (public IP or SSH hostname in console);
• Local terminal (PowerShell/WSL on Windows; macOS/Linux have ssh);
• Code cloned on the instance (or git clone after login);
• Optional: Claude Code or Cursor on your machine for step 4 MCP checks.

Step 1: SSH into Cloud Mac

Copy the instance address from the console and log in as root (or the panel user). Example:

# 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

On first connect, type yes to trust the host key. The prompt should show a remote macOS hostname — everything below runs on that machine, not your laptop.

Step 2: brew install CodeGraph

ZavCloud Cloud Mac is native macOS with Homebrew. Install Node and the CodeGraph CLI (@colbymchenry/codegraph):

# Confirm Homebrew
brew --version

# Install Node if needed
brew install node

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

Prefer one script? Run the official installer in the same SSH session (equivalent, still zero local setup):

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

Step 3: codegraph init (build the index)

At the repo root you will hand to AI agents, initialize and full-index (large repos: add -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/

Use screen or tmux so SSH drops do not kill indexing. When done, .codegraph/codegraph.db stays on Cloud Mac disk — no need to copy the whole repo locally unless you want offline backup.

Step 4: Deploy MCP server (Claude Code / Cursor)

On Cloud Mac, write MCP config (stdio, command codegraph serve --mcp):

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

# Foreground MCP (debug)
codegraph serve --mcp

No duplicate install on your laptop. Two common patterns:

• Claude Code / Cursor Remote on Cloud Mac (SSH remote dev): MCP reads the same .codegraph — zero extra wiring;
• Local agent + cloud graph: expose codegraph serve --mcp via ssh -L or fixed IP — local MCP points at the forwarded port; still no local codegraph init.

Verify: 5-minute checklist

FAQ & hands-on troubleshooting

Ordered by support ticket frequency. Each entry: confirm → run commands → know when it is fixed. Assumes SSH into Cloud Mac and repo cloned under e.g. ~/workspace/your-repo.

SSH fails: ssh root@zavcloud times out or Permission denied

Symptom: Connection timed out, Permission denied (publickey), or failure after the host-key prompt.

Steps:

1. Replace zavcloud with the public IP from the console (e.g. ssh root@203.0.113.10). Unresolved hostnames usually cause timeouts.
2. Check key permissions locally:
   Local

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

   Look for Offering public key in -v output — no mutual signature often means the key is not bound to the instance.
3. If the IP responds but password login fails: Cloud Mac typically uses key auth. Reset the SSH key in the panel or use VNC and enable Remote Login under System Settings → Sharing.
4. Corporate networks blocking port 22: try a phone hotspot once; for static IPv4 on dedicated instances, ask ops to whitelist your IP.

Done when: You get a stable shell and uname -a shows Darwin (macOS), not a Linux container.

brew install or codegraph: command not found

Symptom: brew: command not found after brew install node, or npm i -g succeeds but codegraph --version fails.

Steps:

1. Load Homebrew on Apple Silicon:
   Cloud Mac

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

   If brew is still missing, install Homebrew or use install.sh below (no brew required).
2. Ensure global npm bin is on PATH:
   Cloud Mac

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

   Persist the export PATH=... line in ~/.zshrc so the next SSH session keeps it.
3. Fallback one-liner on Cloud Mac:
   Alternative

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

Done when: which codegraph returns a path and codegraph --version prints a version.

codegraph init -i hangs, or indexing dies when SSH drops

Symptom: No output for a long time; after closing the laptop, codegraph status shows unindexed or corrupt DB.

Steps:

1. Always run indexing inside tmux:
   Cloud Mac · recommended

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

2. Check disk space (index can be hundreds of MB):

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

3. If the DB looks corrupt: back up, delete .codegraph/ at repo root, and rerun codegraph init -i (never delete while the process is running).
4. Large monorepos: use .codegraphignore to skip giant dirs — too aggressive and impact will miss files; tune carefully.

Done when: codegraph status shows indexed file count > 0 and ls .codegraph/codegraph.db exists.

Claude Code / Cursor: no CodeGraph tools — agent still only Greps

Symptom: MCP list has no codegraph; refactors never call codegraph_impact.

Steps:

1. On the Cloud Mac (same user that ran init), rewrite MCP config:

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

   Expect "command": "codegraph" and "args": ["serve", "--mcp"].
2. Quit fully Claude Code / Cursor and reopen (closing the window is not enough).
3. Local agent + remote graph: point MCP at SSH (test manually first):
   Local ~/.claude.json snippet

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

   Run ssh root@YOUR_IP codegraph serve --mcp locally before handing off to the agent.
4. If tools need approval: allow mcp__codegraph__* or add a CLAUDE.md rule requiring codegraph_impact before public API edits.

Done when: A fresh chat can list codegraph tools or run impact and return file paths — not empty or grep-only.

codegraph impact or MCP impact returns an empty list

Symptom: Known callers exist but codegraph impact "Foo.bar" returns 0 rows; the agent assumes no other files need edits.

Steps:

1. Confirm you are at the indexed repo root:

   pwd
   codegraph status

2. Match symbol names to the language (Swift: TypeName.method; TS exports may differ from filenames). Try codegraph_callers or search if available.
3. After large merges on Cloud Mac: git pull && codegraph init -i or incremental sync per docs — stale graphs miss new call edges.
4. Generated or vendor dirs excluded by .gitignore may hide real callers from the index.

Done when: Impact returns at least one path for a symbol you know is referenced; results should be ≥ manual grep (graph includes indirect calls).

Multiple repos on one Cloud Mac, or Claude opened the wrong folder

Symptom: Indexed repo A but coding in B; only one project under ~/workspace has .codegraph/.

Steps:

• Run codegraph init -i at each repo root — one .codegraph/ per repo, never on a parent folder.
• cd to the correct root before opening the agent, or open that folder via Remote-SSH.
• Disk tight: full index only on the main monorepo; nightly git pull && codegraph init -i via cron + tmux for large repos.

Done when: Agent workspace root matches the directory that contains .codegraph/codegraph.db.

Query the graph on a laptop without running init locally

Symptom: You want local MCP queries but refuse a 30-minute local index.

Steps:

1. Keep indexing on Cloud Mac; sync only .codegraph/:
   Run on laptop

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

2. Verify with codegraph status at local repo root; run codegraph install for MCP locally — no second init -i required.

Done when: Local codegraph status OK and MCP tools work against the synced DB.

Teams often nightly rsync a "golden index" from the same Cloud Mac to all dev machines.

Cloud Mac sluggish during indexing — fights Xcode builds

Symptom: CPU pegged; builds and index compete on one host.

Steps:

• Run caffeinate -dims inside tmux so sleep does not kill long index jobs.
• Schedule codegraph init -i at night or off-peak — stagger from xcodebuild; see ../openclaw-cloud-automation/openclaw-cloud-automation.html runner notes.
• Full CPU from codegraph is normal; if simulators + index together saturate the box, add a second Cloud Mac as a dedicated index node.

Done when: Index completes without corrupt DB; daytime dev/build stays usable.

What do I actually skip vs local CodeGraph?

There is no “lite” cloud graph — only where compute runs. You skip local Node/Homebrew, fan noise during full parse, and “lid closed, index paused.” You still need SSH, the cloud repo path, and correct MCP wiring (remote dev or SSH wrapper). Concept and missed-edit cases: CodeGraph & AI coding agents; install deep-dive: large-repo CodeGraph guide (2026).

• Concept— Claude Code missed edits & CodeGraph
• Same machine CI— Cloud Mac runner
• Get an instance— Cloud Mac plans