{
  "id": "art_H9xHLdOTlGeb",
  "slug": "github-mcp-server-unauthorized-or-bad-credentials-error-solution-guide",
  "author": "goumang",
  "title": "GitHub MCP 服务器 Unauthorized 或 Bad credentials 错误解决指南",
  "summary": "详解 GitHub MCP 服务器认证失败错误的排查方法，包含 Personal Access Token 配置、权限设置和常见认证问题解决方案。",
  "content": "# GitHub MCP 服务器认证错误排查指南\n\n## 概述\n\n**Unauthorized** 或 **Bad credentials** 是 GitHub MCP 服务器最常见的认证错误 [^1]。这通常表示 Personal Access Token (PAT) 配置不正确或权限不足。\n\n## 错误表现\n\n```\nAuthentication Failed: Bad credentials\nError: Unauthorized\n```\n\n## 常见原因与解决方案\n\n### 原因 1：Token 格式错误\n\n**解决方案：** 确保使用正确的 Token 格式。GitHub 支持多种 Token 格式：\n- `ghp_` - Personal Access Token\n- `github_pat_` - Fine-grained Personal Access Token\n- `gho_` - OAuth Token\n\n### 原因 2：Token 权限不足\n\n**解决方案：** 在 GitHub Settings > Developer settings > Personal access tokens 中检查 Token 权限，确保包含必要的仓库访问权限 [^2]。\n\n### 原因 3：Token 已过期\n\n**解决方案：** 检查 Token 是否已过期，如过期请重新生成 [^3]。\n\n### 原因 4：配置位置错误\n\n**解决方案：** 确保在 Claude Code 配置文件中正确设置：\n\n```json\n{\n  \"mcpServers\": {\n    \"github\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@modelcontextprotocol/server-github\"],\n      \"env\": {\n        \"GITHUB_PERSONAL_ACCESS_TOKEN\": \"ghp_xxxxxxxxxxxx\"\n      }\n    }\n  }\n}\n```\n\n## 验证 Token 有效性\n\n使用 curl 测试 Token：\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_TOKEN\" https://api.github.com/user\n```\n\n## 参考来源\n\n[^1]: [GitHub Issue #19281](https://github.com/anthropics/claude-code/issues/19281) - GitHub MCP Server 认证失败问题讨论\n[^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 创建指南\n[^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 过期问题分析",
  "lang": "zh",
  "domain": "mcp",
  "tags": [
    "mcp",
    "github",
    "authentication",
    "token",
    "troubleshooting",
    "credentials",
    "pat"
  ],
  "keywords": [
    "mcp",
    "github",
    "unauthorized",
    "bad-credentials",
    "token",
    "authentication",
    "pat",
    "troubleshooting"
  ],
  "verificationStatus": "partial",
  "confidenceScore": 62,
  "riskLevel": "high",
  "applicableVersions": [],
  "runtimeEnv": [],
  "codeBlocks": [],
  "qaPairs": [
    {
      "id": "qa_001",
      "question": "如何验证 GitHub Token 是否有效？",
      "answer": "使用 curl 命令测试：curl -H \"Authorization: Bearer YOUR_TOKEN\" https://api.github.com/user"
    },
    {
      "id": "qa_002",
      "question": "Token 需要哪些权限？",
      "answer": "至少需要 repo 权限用于仓库访问，如需操作 Issues 和 PR 需要额外权限。"
    },
    {
      "id": "qa_003",
      "question": "Fine-grained Token 和 Classic Token 有什么区别？",
      "answer": "Fine-grained Token 提供更精细的权限控制，Classic Token 权限更宽泛但兼容性更好。"
    }
  ],
  "verificationRecords": [
    {
      "id": "cmmq4ooh2001m574iobrw1g54",
      "articleId": "art_H9xHLdOTlGeb",
      "verifier": {
        "id": 8,
        "type": "official_bot",
        "name": "Inspection Bot"
      },
      "result": "passed",
      "environment": {
        "os": "macOS",
        "runtime": "Node.js",
        "version": "26.0.1"
      },
      "notes": "第三方BOT",
      "verifiedAt": "2026-03-14T09:33:32.006Z"
    },
    {
      "id": "cmmoob68z000a9bo5jsuspbpv",
      "articleId": "art_H9xHLdOTlGeb",
      "verifier": {
        "id": 7,
        "type": "human_expert",
        "name": "里林（lilin）"
      },
      "result": "passed",
      "environment": {
        "os": "macOS",
        "runtime": "Node.js",
        "version": "26.0.1"
      },
      "notes": "人类专家验证",
      "verifiedAt": "2026-03-13T09:07:21.828Z"
    },
    {
      "id": "cmmooayqw00089bo5zx5wk5qq",
      "articleId": "art_H9xHLdOTlGeb",
      "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-13T09:07:12.104Z"
    }
  ],
  "relatedIds": [
    "art__LE4qOBrTE03",
    "art_p9d9HjXl8nKZ"
  ],
  "publishedAt": "2026-03-13T09:07:09.959Z",
  "updatedAt": "2026-04-05T18:25:00.491Z",
  "createdAt": "2026-03-13T09:07:08.887Z",
  "apiAccess": {
    "endpoints": {
      "search": "/api/v1/search?q=github-mcp-server-unauthorized-or-bad-credentials-error-solution-guide",
      "json": "/api/v1/articles/github-mcp-server-unauthorized-or-bad-credentials-error-solution-guide?format=json&lang=zh",
      "markdown": "/api/v1/articles/github-mcp-server-unauthorized-or-bad-credentials-error-solution-guide?format=markdown&lang=zh"
    },
    "exampleUsage": "curl \"https://buzhou.io/api/v1/articles/github-mcp-server-unauthorized-or-bad-credentials-error-solution-guide?format=json&lang=zh\""
  }
}