GitHub MCP Server

基于Spring Boot的模型上下文协议（MCP）服务器，提供与AI助手如Claude Desktop集成的GitHub工具。

概述

此服务器实现了模型上下文协议，以暴露可以由MCP客户端使用的GitHub操作。它利用GitHub CLI（gh）执行各种GitHub操作，包括仓库管理、问题跟踪、拉取请求管理和更多。这提供了轻量级替代官方GitHub MCP服务器的选择，无需使用Docker。

Claude Desktop快速入门

要使用此服务器与Claude Desktop结合，请在您的Claude配置文件中添加以下内容：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "github": {
      "command": "java",
      "args": ["-jar", "/path/to/gh_mcp_server/build/libs/gh_mcp_server.jar"],
      "env": {}
    }
  }
}

将/path/to/gh_mcp_server替换为您项目的实际路径。

功能

仓库操作

• 列出已认证用户的仓库
• 在GitHub上搜索仓库
• 获取详细的仓库信息
• 列出仓库中的分支
• 创建新的分支
• 从仓库获取文件内容
• 获取提交历史

问题管理

• 列出问题（打开的、关闭的或全部）
• 获取详细的问题信息
• 创建新的问题
• 关闭问题
• 向问题添加评论
• 编辑问题标题和正文

拉取请求管理

• 列出拉取请求
• 获取详细的拉取请求信息
• 创建新的拉取请求
• 合并拉取请求（合并、压缩或重新基准化）
• 关闭拉取请求
• 向拉取请求添加评论

工作流和动作

• 列出仓库中的工作流
• 列出带有可选过滤的工作流运行
• 查看详细的工作流运行信息

发布管理

• 列出发布
• 查看发布详情
• 创建新的发布（带草稿/预发布选项）

用户操作

• 获取已认证用户详情

先决条件

• Java 21或更高版本 - 使用现代Java特性（虚拟线程、记录、模式匹配）
• GitHub CLI（gh） - 必须安装并经过身份验证
• Gradle - 项目中包含包装器

为什么使用这个MCP服务器？

• 🚀 轻量级：无需Docker，纯Java实现
• 🔧 综合性：涵盖完整工作流程的26个GitHub操作
• ⚡ 快速：直接GitHub CLI集成，优化的JSON响应
• 🧪 经过充分测试：75多个测试用例确保可靠性
• 🛡️ 安全：利用现有的GitHub CLI身份验证

设置

1. 安装GitHub CLI

   # macOS
   brew install gh
   
   # 或从https://cli.github.com/下载
   

2. 与GitHub进行身份验证

   gh auth login
   

3. 克隆并构建项目

   git clone <repository-url>
   cd gh_mcp_server
   ./gradlew build
   

   注意：构建会自动创建一个版本无关的符号链接gh_mcp_server.jar → gh_mcp_server-1.0.0.jar

4. 配置Claude Desktop

   构建后，配置Claude以使用此MCP服务器。您有两个选项：

   选项A：使用JAR文件（推荐）

   {
     "mcpServers": {
       "github": {
         "command": "java",
         "args": ["-jar", "/path/to/gh_mcp_server/build/libs/gh_mcp_server.jar"],
         "env": {}
       }
     }
   }
   

   注意：符号链接gh_mcp_server.jar指向当前版本（gh_mcp_server-1.0.0.jar）。这提供了版本无关的部署。对于特定版本的部署，请使用完整的版本文件名。

   选项B：使用Gradle

   {
     "mcpServers": {
       "github": {
         "command": "./gradlew",
         "args": ["bootRun"],
         "cwd": "/path/to/gh_mcp_server",
         "env": {}
       }
     }
   }
   

5. 重启Claude Desktop以加载新的服务器配置

使用示例

配置Claude Desktop后，您可以使用自然语言与GitHub交互：

仓库管理

• "列出我的仓库" → 显示您的仓库及其详细信息
• "列出我的私有仓库" → 根据可见性筛选（公开/私有/内部）
• "搜索具有超过1000颗星的Spring Boot仓库"
• "显示microsoft/vscode仓库的详细信息"
• "获取我项目仓库的最后5次提交"
• "我的项目仓库中存在哪些分支？"

问题跟踪

• "列出我项目中的开放问题" → 列出当前开放的问题
• "显示问题#123的详细信息" → 获取特定问题的信息
• "创建一个新的问题标题为'登录失败错误'，描述..."
• "关闭问题#123，并添加评论'已在最新版本中修复'"

拉取请求管理

• "列出kubernetes/kubernetes仓库中的所有拉取请求"
• "显示PR#456的详细信息"
• "从我的feature-branch到main创建一个拉取请求"
• "使用压缩策略合并PR#789"

CI/CD和发布

• "显示此仓库中的所有工作流" → 列出GitHub Actions
• "最近的工作流运行状态是什么？"
• "列出golang/go仓库的发布"
• "创建一个新的v2.1.0草稿发布"

文件操作

• "获取我项目中的package.json内容"
• "显示主分支中的README文件"

验证

如果服务器无法启动，请检查：

• 已安装Java 21+且位于PATH中
• GitHub CLI已安装并经过身份验证（gh auth status）
• 配置中的JAR文件路径正确
• 已重启Claude Desktop

测试服务器

要独立测试服务器（不使用Claude）：

./gradlew bootRun

服务器将以STDIO模式启动并等待MCP协议消息。然而，为了正常用途，服务器应按照上述配置自动由Claude Desktop运行。

开发命令

# 构建项目并运行所有测试
./gradlew build

# 运行测试（仅验证命令语法）
./gradlew test

# 运行包括GitHub CLI集成测试的测试
./gradlew test -Dtest.gh.integration=true

# 使用Spotless（Google Java格式）格式化代码
./gradlew spotlessApply

# 检查代码格式而不应用更改
./gradlew spotlessCheck

# 清理构建工件
./gradlew clean

# 本地运行服务器进行测试
./gradlew bootRun

测试覆盖率

项目包括全面的测试覆盖：

• 75多个测试用例验证所有26个GitHub操作
• 命令语法测试 - 验证精确的gh命令构造
• 边缘情况测试 - 处理特殊字符、Unicode、空值
• 集成测试 - 可选的真实GitHub CLI执行
• 错误处理测试 - 验证优雅的失败模式

详见src/test/java/com/kousenit/gh_mcp_server/TEST_README.md中的详细测试文档。

配置

服务器使用Spring Boot的默认配置。您可以在src/main/resources/application.properties中自定义设置。

主要配置选项

• github.defaultBranch - 操作的默认分支名称（默认：main）
• spring.threads.virtual.enabled - 启用虚拟线程以提高性能（默认：true）
• MCP服务器以STDIO模式运行以集成CLI

可用操作（总计26个）

仓库操作

• listRepositories - 列出用户的仓库，可选可见性筛选（公开/私有/内部）
• searchRepositories - 搜索GitHub仓库
• getRepository - 获取详细的仓库信息
• getCommitHistory - 获取仓库提交历史，可配置限制
• listBranches - 列出仓库分支
• createBranch - 创建新分支

问题管理

• listIssues - 列出仓库中的问题
• getIssue - 获取特定问题的详细信息
• createIssue - 创建新问题
• closeIssue - 关闭问题
• commentOnIssue - 向问题添加评论
• editIssue - 编辑问题标题/正文

拉取请求管理

• listPullRequests - 列出拉取请求
• getPullRequest - 获取PR详细信息
• createPullRequest - 创建新的拉取请求
• mergePullRequest - 合并PR（合并/压缩/重新基准化）
• closePullRequest - 关闭拉取请求
• commentOnPullRequest - 向PR添加评论

工作流&CI/CD

• listWorkflows - 列出仓库工作流
• listWorkflowRuns - 列出带有过滤的工作流运行
• getWorkflowRun - 获取工作流运行详细信息

发布管理

• listReleases - 列出仓库发布
• getRelease - 获取发布详细信息
• createRelease - 创建新的发布（草稿/预发布选项）

文件&用户操作

• getFileContents - 从仓库获取文件内容
• getMe - 获取已认证用户详细信息

所有操作返回优化的JSON响应，并支持全面的错误处理。

故障排除

常见问题

"gh: 命令未找到"

• 从https://cli.github.com/安装GitHub CLI
• 确保gh在系统PATH中
• 使用gh --version测试

身份验证错误

• 运行gh auth login进行身份验证
• 使用gh auth status检查状态
• 确保您有权访问您尝试访问的仓库

服务器启动失败

• 验证已安装Java 21+：java --version
• 检查Claude配置中的JAR文件路径
• 查看Claude Desktop日志中的错误消息
• 确保服务器没有在其他实例上运行

命令超时

• 大型仓库或慢网络可能导致超时
• 每个操作的默认超时时间为30秒
• 检查您的互联网连接和GitHub API状态

权限被拒绝错误

• 确保GitHub CLI对仓库具有适当的权限
• 对于组织仓库，检查是否具有适当的访问权限
• 某些操作需要写入权限（创建、编辑、合并、关闭）

性能提示

• 使用具体的仓库和所有者名称以获得更快的响应
• 使用适当的限制参数限制搜索结果
• 服务器使用虚拟线程以实现最佳并发性能
• GitHub CLI自动处理速率限制

获取帮助

• 查看GitHub CLI文档：gh help
• 查阅MCP协议：https://modelcontextprotocol.io/
• 对于服务器问题，在application.properties中启用调试日志

部署考虑

JAR版本控制

构建过程生成带有版本号的JAR文件（例如，gh_mcp_server-1.0.0.jar）。在部署或更新时：

1. 初始部署：在您的Claude Desktop配置中使用当前版本：

   "args": ["-jar", "/path/to/gh_mcp_server/build/libs/gh_mcp_server-1.0.0.jar"]
   

2. 版本更新：当更新到新版本时，您必须：

   • 构建新版本：./gradlew build
   • 使用新JAR文件名更新您的Claude Desktop配置
   • 重启Claude Desktop以加载新版本

3. 版本无关部署：为了更轻松地部署，您可以：

   • 使用自动创建的符号链接gh_mcp_server.jar（构建过程中自动创建）
   • 使用Gradle选项（自动使用最新构建）
   • 使用处理版本更新的部署脚本

   自动符号链接管理：构建过程自动创建和维护符号链接：

   • ./gradlew build创建gh_mcp_server.jar → gh_mcp_server-X.Y.Z.jar
   • ./gradlew clean build重新创建正确的版本符号链接
   • 不需要手动符号链接管理

配置管理

• 将您的Claude Desktop配置纳入版本控制
• 记录生产中使用的具体JAR版本
• 考虑在部署脚本中使用环境变量来处理路径

技术栈

• Spring Boot 3.5.0 - 应用框架
• Spring AI 1.0.0 - AI集成和MCP服务器功能
• Java 21 - 支持虚拟线程的编程语言
• GitHub CLI - GitHub API集成
• Gradle - 构建工具
• Spotless - 使用Google Java格式的代码格式化

主要实现特点

• 虚拟线程（Java 21） - 高效的并发I/O操作
• ProcessBuilder - 支持超时的安全命令执行
• 记录（Java 17） - 命令结果的不可变数据结构
• 模式匹配 - 现代Java语法用于类型检查
• 字符串模板 - 使用String.formatted()进行更干净的字符串构造

许可证

本项目根据MIT许可证授权 - 详情参见LICENSE文件。