Gh MCP Server Oauth

带有OAuth设备流的GitHub MCP服务器

一个使用OAuth设备流进行身份验证的安全GitHub MCP（模型上下文协议）服务器。 零硬编码凭据 -所有令牌都安全地存储在操作系统的本机凭据管理器中。

特性

• 安全OAuth设备流身份验证：不需要浏览器重定向
• 操作系统本机凭据存储:

- macOS：钥匙扣 - Windows:凭据管理器 - Linux：特勤局API（libsecret）

• 零硬编码凭据：代码、配置文件或环境变量中没有标记
• 自动令牌管理：检查现有令牌，处理过期
• 全面的GitHub API覆盖范围：repo、issues、PR、代码搜索等

安全亮点

✅ 令牌仅存储在内存和操作系统凭据存储中 ✅ OAuth作用域遵循最小特权原则 ✅ 日志或配置文件中没有令牌 ✅ 令牌过期时自动重新身份验证 ❌ 没有代币承诺给git ❌ 无明文令牌存储

先决条件

• Node.js 18或更高版本
• GitHub帐户
• GitHub OAuth应用程序凭据（请参阅 安装指南)

快速开始

1.克隆和安装

git clone 
cd gh-mcp-server-oauth
npm install

2.创建GitHub OAuth应用程序

跟随 安装指南 创建GitHub OAuth应用程序并获取 client_id.

3.配置

复制示例配置并添加您的OAuth应用程序客户端ID：

cp mcp-config.example.json mcp-config.json

编辑 mcp-config.json:

{
  "github": {
    "client_id": "your_oauth_app_client_id_here",
    "scopes": [
      "repo",
      "read:user",
      "read:org"
    ]
  }
}

重要: mcp-config.json 是gitignore，不应包含令牌，只应包含OAuth应用程序客户端ID。

4.建造

npm run build

5.跑步

npm start

第一次运行时，您将看到：

╔══════════════════════════════════════════════════════════════╗
║            GitHub OAuth Device Flow Authentication           ║
╠══════════════════════════════════════════════════════════════╣
║                                                              ║
║  1. Visit: https://github.com/login/device                   ║
║                                                              ║
║  2. Enter code: XXXX-XXXX                                    ║
║                                                              ║
║  3. Authorize the application                                ║
║                                                              ║
╚══════════════════════════════════════════════════════════════╝

授权后，您的令牌将被安全存储，服务器也已准备就绪！

可用工具

MCP服务器提供以下GitHub工具：

存储库操作

• list_repositories -列出您的存储库
• get_repository -获取存储库详细信息
• get_file_contents -读取文件内容
• create_or_update_file -创建或更新文件

问题

• list_issues -列出存储库问题
• create_issue -创建新问题
• update_issue -更新现有问题

拉取请求

• list_pull_requests -列出拉取请求
• create_pull_request -创建新的拉取请求

搜索

• search_code -在GitHub上搜索代码
• search_repositories -搜索存储库

用户

• get_user_info -获取经过身份验证的用户信息

配置

OAuth范围

默认范围为：

• repo -完全控制私有存储库
• read:user -读取用户配置文件数据
• read:org -读取组织成员资格

您可以在中自定义范围 mcp-config.json 根据您的需求。看 适用于所有可用范围。

许可证管理

检查令牌状态：

# Tokens are stored securely in your OS credential manager
# No command-line access needed - authentication happens automatically

重新验证（撤销并获取新令牌）：

// In code, you can revoke tokens:
import { revokeTokens } from './auth/oauth.js';
await revokeTokens();

运作原理

1. 首次运行：未找到令牌→ OAuth设备流自动启动
2. 后续运行：在操作系统凭据管理器中找到有效令牌→ 使用存储的令牌
3. 令牌已过期：检测过期→ 触发重新身份验证
4. 手动撤销：从凭据管理器中删除令牌→ 下次运行时重新进行身份验证

发展

构建和观看

npm run watch

在开发中运行

npm run dev

清洁建筑

npm run clean
npm run build

故障排除

“找不到配置文件”

确保 mcp-config.json 存在于项目根目录中：

cp mcp-config.example.json mcp-config.json
# Edit and add your client_id

“请求设备代码失败”

检查你的 client_id 在 mcp-config.json 是正确的，并且与您的GitHub OAuth应用程序匹配。

“设备代码已过期”

用户代码将在15分钟后过期。启动新的身份验证流程：

npm start

令牌存储问题

macOS：确保钥匙链访问正常工作 视窗：检查控制面板中的凭据管理器 Linux：确保 libsecret 已安装：

# Ubuntu/Debian
sudo apt-get install libsecret-1-dev

# Fedora
sudo dnf install libsecret-devel

# Arch
sudo pacman -S libsecret

重新验证

要强制重新身份验证，请删除存储的凭据：

macOS:

security delete-generic-password -s "github-mcp-oauth" -a "github-access-token"

视窗：打开凭据管理器→ 删除“github mcp-oauth”条目

Linux:

secret-tool clear service github-mcp-oauth

安全最佳实践

1. 永不承诺 mcp-config.json 如果它包含任何敏感数据（默认情况下被忽略）
2. 仅共享您的OAuth应用程序 client_id （如果使用OAuth应用程序，则永远不要共享客户端机密）
3. 使用最少的OAuth作用域 根据您的用例需要
4. 定期轮换代币 通过撤销和重新认证
5. 保持依赖关系更新 获取安全补丁

建筑

src/
├── auth/
│   ├── oauth.ts          # OAuth Device Flow implementation
│   └── token-storage.ts  # OS credential manager integration
├── github/
│   └── client.ts         # GitHub API client wrapper
├── config.ts             # Configuration loader
└── index.ts              # MCP server implementation

贡献

欢迎投稿！请确保：

• 没有硬编码凭据
• 所有机密都使用操作系统凭据管理器
• 测试通过（实施时）
• 文档已更新

许可证

麻省理工学院

资源

• 模型上下文协议
• MCP-SDK