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 安装分为 5 步（便于搜索引擎抽取的结构）：

步骤 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
codegraph status

步骤 4：重启 Claude Code
完全退出 Claude Code 进程；必须在仓库根目录执行 claude 启动。

步骤 5：验证 MCP 工具

/mcp

成功标志：mcp__github__* · mcp__codegraph__*（可选 mcp__fetch__*）。完成后可进行 GitHub issue 读取与 codegraph_impact 影响分析。下文展开每步命令与MCP 安装报错排错。

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 = AI 的「代码脑图」：符号级索引、影响面分析、影响文件定位。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"]
    }

图谱在云端时，先完成 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

在会话中输入：

/mcp

或提示：「列出当前所有 MCP 工具名称」。须完全退出 Claude Code 进程后再启动，否则新配置不生效。

成功标志：你应该看到什么

冒烟测试（必须执行）

复制进 Claude Code，强制 Agent 走 MCP 而非猜测：

GitHub 测试

用 MCP 读取仓库 YOUR_ORG/YOUR_REPO 的 issue #1 标题，必须调用 GitHub MCP 工具，不要猜测。

CodeGraph 测试

用 codegraph_impact 查询函数 <仓库内真实函数名> 的影响面，列出前 5 个相关文件。

API 测试（可选）

用 Fetch MCP GET https://api.staging.example.com/health，只报告状态码与 body 前 200 字符。

常见问题（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 安装

问 1：为什么 Claude Code 里看不到 MCP？

答：多为 ~/.claude.json JSON 语法错误、Claude Code 未完全重启，或 npx 拉取 MCP 包失败。运行 python3 -m json.tool ~/.claude.json 并完全退出后重开。详见 MCP 工具不显示。

问 2：为什么 GitHub MCP 返回 401？

答：GitHub PAT 未授权目标仓库、细粒度 token 选错仓库，或 token 已过期。确认 Issues/Contents/Metadata 读权限。详见 401 错误修复。

问 3：为什么 CodeGraph impact 为空？

答：工作目录错误，或未完成 codegraph init -i。在构建 .codegraph/ 的同一仓库根目录启动 claude。详见 CodeGraph 返回空。

问 4：是否必须在仓库根目录运行 Claude Code？

答：是。MCP 工具依赖 cwd 对齐——尤其是 CodeGraph MCP。pwd 必须等于执行 codegraph init 的目录。详见 cwd 踩坑。

问 5：安装成功的标志是什么？

答：/mcp 显示 mcp__github__* 与 mcp__codegraph__*；若已配置预发 Fetch，还应有 mcp__fetch__*。详见 成功标志。