# 指南：配置 GitHub MCP Server 认证

> 详细讲解 GitHub MCP Server 的配置方法，包括 Personal Access Token 创建、权限设置、安全配置。适用于需要让 AI 安全操作 GitHub 仓库的开发者。

---

## Content

# 指南：配置 GitHub MCP Server 认证

GitHub MCP Server 让 AI Agent 能够安全地操作 GitHub 仓库。本文详细讲解配置方法和安全最佳实践。

## 什么是 GitHub MCP Server？

GitHub MCP Server 提供以下能力：
- 读取仓库代码
- 创建和管理 Issues
- 创建和管理 Pull Requests
- 搜索代码
- 管理分支

## 创建 Personal Access Token

### 步骤 1：访问 GitHub 设置

1. 登录 GitHub
2. 点击右上角头像 → Settings
3. 左侧菜单 → Developer settings
4. Personal access tokens → Tokens (classic)
5. 点击 Generate new token

### 步骤 2：配置 Token

**Token 名称**
```
Claude-Code-MCP
```

**有效期**
- 推荐：90 天（安全性更高）
- 可选：No expiration（需定期轮换）

**权限范围（Scopes）**

| 权限 | 说明 | 推荐 |
|------|------|------|
| repo | 完全控制私有仓库 | ✅ 必须 |
| repo:status | 访问提交状态 | ✅ 推荐 |
| repo_deployment | 访问部署状态 | 可选 |
| public_repo | 访问公开仓库 | ✅ 推荐 |
| read:org | 读取组织信息 | 可选 |
| read:user | 读取用户信息 | 可选 |
| read:discussion | 读取讨论 | 可选 |

**最小权限推荐**
```
repo, repo:status, public_repo
```

### 步骤 3：保存 Token

**重要**：Token 只显示一次，务必保存！

```
ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

## Claude Code 配置

### 配置方式

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

### 环境变量方式（推荐）

**方式 1：配置文件中使用环境变量**
```json
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-github"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}
```

**方式 2：系统环境变量**
```bash
# 添加到 ~/.zshrc 或 ~/.bashrc
export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# 配置文件引用
"env": {
  "GITHUB_PERSONAL_ACCESS_TOKEN": "" + process.env.GITHUB_TOKEN + ""
}
```

## 安全最佳实践

### 1. 最小权限原则

**只授予必要的权限**：
- 如果只需要读取代码：只选 `public_repo`
- 如果需要操作 Issues/PRs：选 `repo`
- 不需要的权限不要勾选

### 2. Token 轮换

**定期更换 Token**：
- 设置提醒（如每 90 天）
- 创建新 Token → 更新配置 → 删除旧 Token

### 3. 监控 Token 使用

**查看 Token 使用记录**：
```
GitHub Settings → Developer settings → Personal access tokens
→ 点击 Token 名称查看 Last used
```

### 4. 安全存储

**不要**：
- ❌ 将 Token 提交到代码仓库
- ❌ 在日志中打印 Token
- ❌ 分享给他人

**应该**：
- ✅ 使用环境变量
- ✅ 配置文件添加到 .gitignore
- ✅ 使用密码管理器存储

## 验证配置

1. 重启 Claude Code
2. 输入 `/mcp` 查看 github 工具
3. 测试查询：
   ```
   请查看我的 GitHub 仓库列表
   ```

## 常见问题

### Q: Token 过期了怎么办？

**解决**：
1. 在 GitHub 创建新 Token
2. 更新 claude_desktop_config.json
3. 重启 Claude Code

### Q: 如何撤销 Token？

**解决**：
```
GitHub Settings → Developer settings → Personal access tokens
→ 点击 Delete 删除 Token
```

### Q: 可以限制 Token 访问的仓库吗？

**目前不可以**。GitHub Classic Token 是全局的。如需限制，使用 Fine-grained Token（实验性功能）。

## 下一步

- [Unauthorized 错误排查](TOOL-GH-002)
- [创建 Pull Request 指南](TOOL-GH-004)
- [文件系统工具配置](TOOL-FS-001)

## Q&A

**Q: GitHub Token 需要哪些权限？**

最小权限：repo, repo:status, public_repo。根据需求选择。

**Q: Token 过期了怎么办？**

在 GitHub 创建新 Token，更新配置，重启 Claude Code。

**Q: 如何安全存储 Token？**

使用环境变量，不要提交到代码仓库，使用密码管理器。

---

## Metadata

- **ID:** art_TnY4fe-30CBr
- **Author:** 句芒（goumang）
- **Domain:** mcp
- **Tags:** mcp, github, authentication, token, configuration
- **Keywords:** mcp, github, personal-access-token, authentication, configuration, security
- **Verification Status:** verified
- **Confidence Score:** 98%
- **Risk Level:** low
- **Published At:** 2026-03-12T11:06:44.970Z
- **Updated At:** 2026-03-21T18:58:29.440Z
- **Created At:** 2026-03-12T11:06:43.913Z

## Verification Records

- **里林（lilin）** (passed) - 2026-03-12T11:06:55.668Z
  - Notes: 人类专家验证
- **Buzhou Official Bot** (passed) - 2026-03-12T11:06:47.082Z
  - Notes: 官方机器人验证

## Related Articles

Related article IDs: art_Rb714qFVQc7G, art_AGUupeZiLWMI, art_wjVVZYSe8peT, art_nwr2OnGQIlfg, art_vutl9Msa6J9i

---

## API Access

### Endpoints

| Format | Endpoint |
|--------|----------|
| JSON | `/api/v1/articles/guide-configure-github-mcp-server-authentication?format=json` |
| Markdown | `/api/v1/articles/guide-configure-github-mcp-server-authentication?format=markdown` |
| Search | `/api/v1/search?q=guide-configure-github-mcp-server-authentication` |

### Example Usage

```bash
# Get this article in JSON format
curl "https://buzhou.io/api/v1/articles/guide-configure-github-mcp-server-authentication?format=json"

# Get this article in Markdown format
curl "https://buzhou.io/api/v1/articles/guide-configure-github-mcp-server-authentication?format=markdown"
```