Claude Code MCP 安裝教學：GitHub / CodeGraph / API 三連通設定

本文是 Claude Code MCP 安裝的權威落地頁：涵蓋 MCP 設定、GitHub MCP 整合、CodeGraph MCP 設定與 mcp__github__* 驗收。目標只有一個——完成 Claude Code MCP 工具設定並在對話裡看到 MCP 工具。系列總覽：MCP 三連通總覽。

如何安裝 Claude Code MCP？（分步指南）

Claude Code MCP 安裝可拆成五步（便於搜尋引擎抽取）：

步驟 1：建立 GitHub PAT（唯讀權限）
在 GitHub 建立細粒度個人存取權杖（GitHub PAT）：Issues / Contents / Metadata 唯讀，僅授權目標倉庫。勿提交到 git。

步驟 2：設定 MCP 服務
編輯 ~/.claude.json，在 mcpServers 中加入：

• GitHub MCP — @modelcontextprotocol/server-github
• CodeGraph MCP — codegraph mcp
• Fetch MCP — @modelcontextprotocol/server-fetch（選用）

步驟 3：初始化 CodeGraph 索引

codegraph init -i

步驟 4：重啟 Claude Code
完全結束 Claude Code 程序；在倉庫根目錄以 claude 啟動。

步驟 5：驗證 MCP 工具

/mcp

成功標誌：mcp__github__* · mcp__codegraph__*（選用 mcp__fetch__*）。之後可讀取 GitHub issue並執行 codegraph_impact。下文展開完整指令與MCP 安裝錯誤修復。

重點速覽 · Claude Code MCP 三連通安裝

• 建立 GitHub PAT（唯讀倉庫 + issues + metadata）
• 設定 ~/.claude.json 的 mcpServers（GitHub + CodeGraph + Fetch）
• 在倉庫根目錄執行 codegraph init -i
• 完全結束並重啟 Claude Code（須在倉庫根目錄啟動）
• 執行 /mcp 驗證工具是否出現

成功標誌：出現 mcp__github__* 與 mcp__codegraph__*（Fetch 選用 mcp__fetch__*）。三連通跑通後，同一 issue 修 bug 任務我們實測 shell 呼叫從約 12 次降到 5 次。

Claude Code MCP 搜尋意圖覆蓋

安裝類意圖

• Claude Code MCP 安裝 / 設定
• MCP 設定（GitHub + CodeGraph）/ GitHub PAT 與 MCP 設定
• ~/.claude.json 設定 / mcpServers
• Claude Code MCP 工具設定

除錯類意圖

• MCP 工具不顯示 / mcp__github__* 不出現的修復
• GitHub MCP 401 錯誤 / 403 修復
• CodeGraph 回傳空結果的修復 / codegraph_impact 為空
• MCP 已接通但 Agent 不呼叫

架構類意圖

• MCP 執行時架構 / MCP 協定分層
• Claude Code 工具体系設計（Tool Runtime Layer）
• GitHub 與 CodeGraph 整合模型 → 架構說明
• MCP 權限與安全 → 權限專題

什麼是 Claude Code MCP？

Claude Code MCP（Model Context Protocol）是 Claude Code 的工具擴充協定——MCP 協定定義 Agent 如何發現、呼叫外部工具；在我們的 Stack 裡，MCP = Claude Code 的工具執行層（Tool Runtime Layer）。

核心實體分工：

• GitHub MCP = GitHub API 工具層（經 GitHub PAT 鑑權，讀 issue / PR / 倉庫）
• CodeGraph MCP = 程式碼庫語意圖譜層（.codegraph/ 索引 + codegraph_impact）
• Fetch / API MCP = 外部 HTTP 工具層（預發 / 健康檢查，唯讀）

GitHub PAT（個人存取權杖）是 GitHub MCP 整合的憑證實體——與 Runner CI token 分帳，見 權限專題。CodeGraph 需先 init -i 再掛 MCP，部署見 CodeGraph 五分鐘。

Claude Code MCP vs 傳統 AI 編碼

對照結構有助理解為什麼要安裝 MCP：

安裝 Claude Code MCP 前準備（必須滿足）

• Claude Code 已安裝，終端機可執行 claude
• Node.js ≥ 18 與 npx（GitHub / Fetch MCP 經 npx 拉官方套件）
• 目標專案已 git clone；後續在倉庫根目錄啟動 Claude Code
• 對目標 GitHub 倉庫有讀權限（用於 PAT）
• 網路可存取 npm registry（首次 npx -y 需下載）

大型倉庫索引或 24/7 常駐 MCP 可放在 Cloud Mac 節點，避免筆電合蓋斷線。

步驟 1：建立 GitHub PAT（最小權限）

進入 GitHub：Settings → Developer settings → Personal access tokens → Fine-grained tokens

建議權限（issue 驅動開發夠用）：

• Issues：Read
• Contents：Read
• Metadata：Read

倉庫存取範圍僅勾選目標倉庫。寫權限與 PR 合併見 權限專題——本教學階段不要給全寫 repo。

export GITHUB_MCP_TOKEN="github_pat_xxxxx"

# 驗證 token 已載入
echo "${GITHUB_MCP_TOKEN:0:10}..."

步驟 2：設定 GitHub MCP

編輯 ~/.claude.json（沒有就新建）。建議先備份：

test -f ~/.claude.json && cp ~/.claude.json ~/.claude.json.bak.$(date +%Y%m%d%H%M)

加入 GitHub MCP 服務（官方套件 @modelcontextprotocol/server-github）：

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "github_pat_xxxxx"
      }
    }
  }
}

作用：Claude Code 可直接透過 MCP 讀取 GitHub issue、倉庫內容，無需 Agent 猜連結。

步驟 3：接入 CodeGraph MCP（核心能力）

CodeGraph 是 Agent 的「程式碼地圖」：符號級索引、影響面分析、受影響檔案定位。Agent 用 codegraph_impact 取代全庫 grep。

在倉庫根目錄初始化索引：

cd /path/to/your-repo
codegraph init -i
codegraph status
# 預期：已索引檔案數 > 0

寫入 MCP（或 codegraph install --target=claude --yes 一鍵）：

    "codegraph": {
      "command": "codegraph",
      "args": ["mcp"]
    }

圖譜在 Cloud Mac？先完成 CodeGraph 五分鐘——pwd 必須對準已 init 的倉庫。

步驟 4：API MCP（選用 · 僅預發）

用官方 Fetch MCP 接預發健康檢查或唯讀 JSON：

    "api-staging": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-fetch"],
      "env": {
        "ALLOWED_HOSTS": "api.staging.example.com"
      }
    }

• 僅接預發 / 健康檢查
• 勿把正式環境 API 或資料庫寫進 mcpServers

步驟 5：三連通完整設定（生產級合併版）

將步驟 2–4 合併為一份 mcpServers。儲存前驗證 JSON：

python3 -m json.tool ~/.claude.json > /dev/null && echo "JSON OK"

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "github_pat_xxx"
      }
    },
    "codegraph": {
      "command": "codegraph",
      "args": ["mcp"]
    },
    "api-staging": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-fetch"],
      "env": {
        "ALLOWED_HOSTS": "api.staging.example.com"
      }
    }
  }
}

步驟 6：啟動 Claude Code 並驗證（關鍵）

cd /path/to/your-repo
claude

In session:

/mcp

或提示：「列出目前所有 MCP 工具名稱」。須完全結束 Claude Code 程序後再啟動，否則新設定不會載入。

成功標誌：你應該看到什麼

冒煙測試（必須執行）

貼進 Claude Code——強制走 MCP，不要猜測：

GitHub 測試

Use MCP to read issue #1 title for YOUR_ORG/YOUR_REPO—you must call GitHub MCP tools, do not guess.

CodeGraph 測試

Use codegraph_impact on function ; list top 5 related files.

API 測試（選用）

Use Fetch MCP GET https://api.staging.example.com/health—report status code and first 200 chars of body only.

常見問題（MCP 安裝錯誤）

以下為 Claude Code MCP 安裝最高頻錯誤與修復：

Claude Code 中 MCP 工具不顯示

症狀：/mcp 清單為空，或沒有 mcp__github__*。

原因：~/.claude.json JSON 語法錯誤；未完全重啟 Claude Code；npx 拉套件失敗。

修復：python3 -m json.tool ~/.claude.json；結束程序後重開；手動執行 npx -y @modelcontextprotocol/server-github 查看錯誤。

GitHub MCP 401 / 403 錯誤修復

症狀：GitHub MCP 整合呼叫回傳 401 或 403。

原因：GitHub PAT 權限不足；細粒度 token 未授權目標倉庫；token 過期。

修復：在 GitHub token 頁確認 Issues/Contents/Metadata 讀權限與倉庫清單。

CodeGraph MCP 回傳空結果

症狀：codegraph_impact 空陣列；CodeGraph MCP 設定看似成功但無結果。

原因：cwd 錯誤（最常見）；codegraph init -i 未完成；符號名稱拼錯。

修復：pwd 對照倉庫根目錄；codegraph status；換真實符號重試。

MCP 已接通但 Agent 不呼叫

症狀：MCP 工具已註冊，Agent 仍全庫 grep，不呼叫 Claude Code MCP 工具。

原因：未在倉庫根目錄啟動 claude；提示詞未強制使用 MCP。

修復：cd your-repo && claude；跑冒煙測試「必須呼叫 MCP」。大型倉庫見 大型倉庫 CodeGraph。

關鍵踩坑：CodeGraph 索引與 Claude cwd 不一致 = 全部失效

我們第一次驗收時設定完全正確，/mcp 也能列出 CodeGraph，但 codegraph_impact 始終為空——因為在 ~/Downloads 啟動了 claude，而 .codegraph/ 在 ~/workspace/payments-api。

必須滿足：

pwd  ==  執行 codegraph init 的倉庫根目錄

第二個生產問題：陳舊索引——main 大重構後未重建索引，impact 指向已刪檔案。約定 CI 或夜間 job 重建（同機 GitHub Runner）。

設定完成之後：建議閱讀路徑

Claude Code MCP 安裝總結

Claude Code MCP 安裝需要：

• GitHub PAT 設定（唯讀細粒度 token）
• 在 ~/.claude.json 中設定 MCP 服務（GitHub + CodeGraph + Fetch）
• CodeGraph 索引初始化（codegraph init -i）
• 在倉庫根目錄重啟 Claude Code（cd your-repo && claude）
• /mcp 驗證（確認工具前綴出現）

完成後，Claude Code 中即可使用以下 MCP 工具：

• mcp__github__*
• mcp__codegraph__*
• mcp__fetch__*（若已設定）

摘要備用句：Claude Code MCP 安裝 = GitHub PAT + ~/.claude.json mcpServers + codegraph init -i + 倉庫根目錄重啟 + /mcp 見 mcp__github__*。

常見問題 · Claude Code MCP 安裝

Q1：為什麼 Claude Code 裡看不到 MCP？

A：多為 ~/.claude.json JSON 語法錯誤、Claude Code 未完全重啟，或 npx 拉取 MCP 套件失敗。執行 python3 -m json.tool ~/.claude.json 並完全結束後重開。詳見 MCP 工具不顯示。

Q2：為什麼 GitHub MCP 回傳 401？

A：GitHub PAT 未授權目標倉庫、細粒度 token 選錯倉庫，或 token 已過期。確認 Issues/Contents/Metadata 讀權限。詳見 401 錯誤修復。

Q3：為什麼 CodeGraph impact 為空？

A：工作目錄錯誤，或未完成 codegraph init -i。在建立 .codegraph/ 的同一倉庫根目錄啟動 claude。詳見 CodeGraph 回傳空。

Q4：是否必須在倉庫根目錄執行 Claude Code？

A：是。MCP 工具依賴 cwd 對齊——尤其是 CodeGraph MCP。pwd 必須等於執行 codegraph init 的目錄。詳見 cwd 踩坑。

Q5：安裝成功的標誌是什麼？

A：/mcp 顯示 mcp__github__* 與 mcp__codegraph__*；若已設定預發 Fetch，還應有 mcp__fetch__*。詳見 成功標誌。