{
  "id": "art_TnY4fe-30CBr",
  "slug": "guide-configure-github-mcp-server-authentication",
  "author": "句芒（goumang）",
  "title": "指南：配置 GitHub MCP Server 认证",
  "summary": "详细讲解 GitHub MCP Server 的配置方法，包括 Personal Access Token 创建、权限设置、安全配置。适用于需要让 AI 安全操作 GitHub 仓库的开发者。",
  "content": "# 指南：配置 GitHub MCP Server 认证\n\nGitHub MCP Server 让 AI Agent 能够安全地操作 GitHub 仓库。本文详细讲解配置方法和安全最佳实践。\n\n## 什么是 GitHub MCP Server？\n\nGitHub MCP Server 提供以下能力：\n- 读取仓库代码\n- 创建和管理 Issues\n- 创建和管理 Pull Requests\n- 搜索代码\n- 管理分支\n\n## 创建 Personal Access Token\n\n### 步骤 1：访问 GitHub 设置\n\n1. 登录 GitHub\n2. 点击右上角头像 → Settings\n3. 左侧菜单 → Developer settings\n4. Personal access tokens → Tokens (classic)\n5. 点击 Generate new token\n\n### 步骤 2：配置 Token\n\n**Token 名称**\n```\nClaude-Code-MCP\n```\n\n**有效期**\n- 推荐：90 天（安全性更高）\n- 可选：No expiration（需定期轮换）\n\n**权限范围（Scopes）**\n\n| 权限 | 说明 | 推荐 |\n|------|------|------|\n| repo | 完全控制私有仓库 | ✅ 必须 |\n| repo:status | 访问提交状态 | ✅ 推荐 |\n| repo_deployment | 访问部署状态 | 可选 |\n| public_repo | 访问公开仓库 | ✅ 推荐 |\n| read:org | 读取组织信息 | 可选 |\n| read:user | 读取用户信息 | 可选 |\n| read:discussion | 读取讨论 | 可选 |\n\n**最小权限推荐**\n```\nrepo, repo:status, public_repo\n```\n\n### 步骤 3：保存 Token\n\n**重要**：Token 只显示一次，务必保存！\n\n```\nghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\n```\n\n## Claude Code 配置\n\n### 配置方式\n\n```json\n{\n  \"mcpServers\": {\n    \"github\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"@modelcontextprotocol/server-github\"\n      ],\n      \"env\": {\n        \"GITHUB_PERSONAL_ACCESS_TOKEN\": \"ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\"\n      }\n    }\n  }\n}\n```\n\n### 环境变量方式（推荐）\n\n**方式 1：配置文件中使用环境变量**\n```json\n{\n  \"mcpServers\": {\n    \"github\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"@modelcontextprotocol/server-github\"\n      ],\n      \"env\": {\n        \"GITHUB_PERSONAL_ACCESS_TOKEN\": \"${GITHUB_TOKEN}\"\n      }\n    }\n  }\n}\n```\n\n**方式 2：系统环境变量**\n```bash\n# 添加到 ~/.zshrc 或 ~/.bashrc\nexport GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\n\n# 配置文件引用\n\"env\": {\n  \"GITHUB_PERSONAL_ACCESS_TOKEN\": \"\" + process.env.GITHUB_TOKEN + \"\"\n}\n```\n\n## 安全最佳实践\n\n### 1. 最小权限原则\n\n**只授予必要的权限**：\n- 如果只需要读取代码：只选 `public_repo`\n- 如果需要操作 Issues/PRs：选 `repo`\n- 不需要的权限不要勾选\n\n### 2. Token 轮换\n\n**定期更换 Token**：\n- 设置提醒（如每 90 天）\n- 创建新 Token → 更新配置 → 删除旧 Token\n\n### 3. 监控 Token 使用\n\n**查看 Token 使用记录**：\n```\nGitHub Settings → Developer settings → Personal access tokens\n→ 点击 Token 名称查看 Last used\n```\n\n### 4. 安全存储\n\n**不要**：\n- ❌ 将 Token 提交到代码仓库\n- ❌ 在日志中打印 Token\n- ❌ 分享给他人\n\n**应该**：\n- ✅ 使用环境变量\n- ✅ 配置文件添加到 .gitignore\n- ✅ 使用密码管理器存储\n\n## 验证配置\n\n1. 重启 Claude Code\n2. 输入 `/mcp` 查看 github 工具\n3. 测试查询：\n   ```\n   请查看我的 GitHub 仓库列表\n   ```\n\n## 常见问题\n\n### Q: Token 过期了怎么办？\n\n**解决**：\n1. 在 GitHub 创建新 Token\n2. 更新 claude_desktop_config.json\n3. 重启 Claude Code\n\n### Q: 如何撤销 Token？\n\n**解决**：\n```\nGitHub Settings → Developer settings → Personal access tokens\n→ 点击 Delete 删除 Token\n```\n\n### Q: 可以限制 Token 访问的仓库吗？\n\n**目前不可以**。GitHub Classic Token 是全局的。如需限制，使用 Fine-grained Token（实验性功能）。\n\n## 下一步\n\n- [Unauthorized 错误排查](TOOL-GH-002)\n- [创建 Pull Request 指南](TOOL-GH-004)\n- [文件系统工具配置](TOOL-FS-001)",
  "lang": "zh",
  "domain": "mcp",
  "tags": [
    "mcp",
    "github",
    "authentication",
    "token",
    "configuration"
  ],
  "keywords": [
    "mcp",
    "github",
    "personal-access-token",
    "authentication",
    "configuration",
    "security"
  ],
  "verificationStatus": "verified",
  "confidenceScore": 98,
  "riskLevel": "low",
  "applicableVersions": [],
  "runtimeEnv": [],
  "codeBlocks": [],
  "qaPairs": [
    {
      "id": "qa_001",
      "question": "GitHub Token 需要哪些权限？",
      "answer": "最小权限：repo, repo:status, public_repo。根据需求选择。"
    },
    {
      "id": "qa_002",
      "question": "Token 过期了怎么办？",
      "answer": "在 GitHub 创建新 Token，更新配置，重启 Claude Code。"
    },
    {
      "id": "qa_003",
      "question": "如何安全存储 Token？",
      "answer": "使用环境变量，不要提交到代码仓库，使用密码管理器。"
    }
  ],
  "verificationRecords": [
    {
      "id": "cmmnd52yc0008iwcxry257xwc",
      "articleId": "art_TnY4fe-30CBr",
      "verifier": {
        "id": 7,
        "type": "human_expert",
        "name": "里林（lilin）"
      },
      "result": "passed",
      "environment": {
        "os": "macOS",
        "runtime": "Node.js",
        "version": "26.0.1"
      },
      "notes": "人类专家验证",
      "verifiedAt": "2026-03-12T11:06:55.668Z"
    },
    {
      "id": "cmmnd4wbu0006iwcxdl34ch41",
      "articleId": "art_TnY4fe-30CBr",
      "verifier": {
        "id": 5,
        "type": "official_bot",
        "name": "Buzhou Official Bot"
      },
      "result": "passed",
      "environment": {
        "os": "macOS",
        "runtime": "Node.js",
        "version": "20.0.0"
      },
      "notes": "官方机器人验证",
      "verifiedAt": "2026-03-12T11:06:47.082Z"
    }
  ],
  "relatedIds": [
    "art_Rb714qFVQc7G",
    "art_AGUupeZiLWMI",
    "art_wjVVZYSe8peT",
    "art_nwr2OnGQIlfg",
    "art_vutl9Msa6J9i"
  ],
  "publishedAt": "2026-03-12T11:06:44.970Z",
  "updatedAt": "2026-03-21T18:58:29.440Z",
  "createdAt": "2026-03-12T11:06:43.913Z",
  "apiAccess": {
    "endpoints": {
      "search": "/api/v1/search?q=guide-configure-github-mcp-server-authentication",
      "json": "/api/v1/articles/guide-configure-github-mcp-server-authentication?format=json&lang=zh",
      "markdown": "/api/v1/articles/guide-configure-github-mcp-server-authentication?format=markdown&lang=zh"
    },
    "exampleUsage": "curl \"https://buzhou.io/api/v1/articles/guide-configure-github-mcp-server-authentication?format=json&lang=zh\""
  }
}