Cloud Mac에 CodeGraph MCP 설치 — 5분 가이드

대형 저장소에서 codegraph init하면 노트북 팬이 먼저 돕니다. 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만;
• 상시 노드 야간 인덱스, 낮엔 읽기 전용.

사전 준비

• Cloud Mac 개통;
• 로컬 터미널;
• 클라우드 clone;
• 선택: Claude Code/Cursor.

1단계: 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 — 이후 작업은 노트북이 아님.

2단계: brew install

네이티브 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

공식 install.sh도 동일 SSH 세션에서:

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

3단계: codegraph init

Agent에 넘길 저장소 루트에서 전체 인덱스:

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·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 vs no mutual signature — 후자는 키 미등록일 때가 많습니다.
3. IP는 되지만 비밀번호 거부: Cloud Mac은 보통 키 로그인입니다. 패널에서 SSH 키 재설정 또는 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 없음

증상: 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건; Agent가 다른 파일 수정 불필요로 판단.

처리 단계:

1. 인덱스된 저장소 루트 확인:

   pwd
   codegraph status

2. 심볼명을 언어에 맞게(Swift: TypeName.method). codegraph_callers로 철자 확인.
3. 인덱스 만료: Cloud Mac에서 git pull && codegraph init -i.
4. .gitignore가 호출자 디렉터리 전체를 제외하지 않았는지 확인.

완료 기준: 알려진 참조 심볼에 impact ≥1 경로; 결과는 수동 grep 이상(간접 호출 포함).

Cloud Mac 다중 저장소 또는 잘못된 폴더

증상: A에서 init, B에서 코딩; ~/workspace 중 하나만 .codegraph/ 보유.

처리 단계:

• 각 저장소 루트에서 개별 codegraph init -i — 부모 폴더 공유 금지.
• Agent 전 올바른 루트로 cd 또는 Remote-SSH로 해당 폴더 열기.
• 디스크 부족: 메인 monorepo만 전체 인덱스; 야간 cron + tmux로 갱신.

완료 기준: Agent 워크스페이스 루트 = .codegraph/codegraph.db 위치.

로컬 init 없이 노트북에서 그래프 조회

증상: 로컬 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 full CPU는 정상; 시뮬레이터 병행 시 인덱스 전용 Cloud Mac 추가 검토.

완료 기준: 인덱스 완료·DB 정상; 주간 개발/빌드 사용 가능.

로컬 install 대비 무엇을 생략?

기능 동일 — 연산 위치만 다름. CodeGraph AI 코딩; 대형 저장소 가이드（2026）.

• 개념— Claude Code 수정 누락
• CI 동기— Cloud Mac Runner
• 인스턴스— Cloud Mac 요금