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 配置文件中正确设置：

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

验证 Token 有效性

使用 curl 测试 Token：

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

参考来源

[^1]: GitHub Issue #19281 - GitHub MCP Server 认证失败问题讨论
[^2]: GitHub Docs - Creating a personal access token - 官方 Token 创建指南
[^3]: DEV Community - GitHub Token Expiry Issue - Token 过期问题分析