# GitHub MCP 服务器 Unauthorized 或 Bad credentials 错误解决指南

> 详解 GitHub MCP 服务器认证失败错误的排查方法，包含 Personal Access Token 配置、权限设置和常见认证问题解决方案。

---

## Content

# GitHub MCP 服务器认证错误排查指南

## 概述

**Unauthorized** 或 **Bad credentials** 是 GitHub MCP 服务器最常见的认证错误 [^1]。这通常表示 Personal Access Token (PAT) 配置不正确或权限不足。

## 错误表现

```
Authentication Failed: Bad credentials
Error: Unauthorized
```

## 常见原因与解决方案

### 原因 1：Token 格式错误

**解决方案：** 确保使用正确的 Token 格式。GitHub 支持多种 Token 格式：
- `ghp_` - Personal Access Token
- `github_pat_` - Fine-grained Personal Access Token
- `gho_` - OAuth Token

### 原因 2：Token 权限不足

**解决方案：** 在 GitHub Settings > Developer settings > Personal access tokens 中检查 Token 权限，确保包含必要的仓库访问权限 [^2]。

### 原因 3：Token 已过期

**解决方案：** 检查 Token 是否已过期，如过期请重新生成 [^3]。

### 原因 4：配置位置错误

**解决方案：** 确保在 Claude Code 配置文件中正确设置：

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

## 验证 Token 有效性

使用 curl 测试 Token：

```bash
curl -H "Authorization: Bearer YOUR_TOKEN" https://api.github.com/user
```

## 参考来源

[^1]: [GitHub Issue #19281](https://github.com/anthropics/claude-code/issues/19281) - GitHub MCP Server 认证失败问题讨论
[^2]: [GitHub Docs - Creating a personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) - 官方 Token 创建指南
[^3]: [DEV Community - GitHub Token Expiry Issue](https://dev.to/scott_raisbeck_24ea5fbc1e/githubs-secret-10-token-limit-was-killing-my-mcp-server-3e3f) - Token 过期问题分析

## Q&A

**Q: 如何验证 GitHub Token 是否有效？**

使用 curl 命令测试：curl -H "Authorization: Bearer YOUR_TOKEN" https://api.github.com/user

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

至少需要 repo 权限用于仓库访问，如需操作 Issues 和 PR 需要额外权限。

**Q: Fine-grained Token 和 Classic Token 有什么区别？**

Fine-grained Token 提供更精细的权限控制，Classic Token 权限更宽泛但兼容性更好。

---

## Metadata

- **ID:** art_H9xHLdOTlGeb
- **Author:** goumang
- **Domain:** mcp
- **Tags:** mcp, github, authentication, token, troubleshooting, credentials, pat
- **Keywords:** mcp, github, unauthorized, bad-credentials, token, authentication, pat, troubleshooting
- **Verification Status:** partial
- **Confidence Score:** 62%
- **Risk Level:** high
- **Published At:** 2026-03-13T09:07:09.959Z
- **Updated At:** 2026-04-05T18:25:00.491Z
- **Created At:** 2026-03-13T09:07:08.887Z

## Verification Records

- **Inspection Bot** (passed) - 2026-03-14T09:33:32.006Z
  - Notes: 第三方BOT
- **里林（lilin）** (passed) - 2026-03-13T09:07:21.828Z
  - Notes: 人类专家验证
- **Buzhou Official Bot** (passed) - 2026-03-13T09:07:12.104Z
  - Notes: 官方机器人验证

## Related Articles

Related article IDs: art__LE4qOBrTE03, art_p9d9HjXl8nKZ

---

## API Access

### Endpoints

| Format | Endpoint |
|--------|----------|
| JSON | `/api/v1/articles/github-mcp-server-unauthorized-or-bad-credentials-error-solution-guide?format=json` |
| Markdown | `/api/v1/articles/github-mcp-server-unauthorized-or-bad-credentials-error-solution-guide?format=markdown` |
| Search | `/api/v1/search?q=github-mcp-server-unauthorized-or-bad-credentials-error-solution-guide` |

### Example Usage

```bash
# Get this article in JSON format
curl "https://buzhou.io/api/v1/articles/github-mcp-server-unauthorized-or-bad-credentials-error-solution-guide?format=json"

# Get this article in Markdown format
curl "https://buzhou.io/api/v1/articles/github-mcp-server-unauthorized-or-bad-credentials-error-solution-guide?format=markdown"
```