GitHub MCP Server

GitHub MCP 服务

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

概述

此服务实现了模型上下文协议，可将 GitHub 操作作为工具提供给 MCP 客户端使用。它借助 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 上的仓库
• 获取仓库详细信息
• 列出仓库中的分支
• 创建新分支
• 获取仓库中的文件内容
• 获取提交历史

问题管理

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

拉取请求管理

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

工作流和 Actions

• 列出仓库中的工作流
• 列出工作流运行记录，并可选择筛选
• 查看工作流运行记录的详细信息

发布管理

• 列出发布
• 查看发布详情
• 创建新发布（可选择草稿或预发布）

用户操作

• 获取已认证用户的详细信息

前置条件

• Java 21 或更高版本——使用现代 Java 功能（虚拟线程、记录类、模式匹配）
• GitHub CLI（gh）——必须已安装并完成认证
• Gradle——项目中包含 Wrapper

为什么使用此 MCP 服务？

• 🚀 轻量级：无需 Docker，纯 Java 实现
• 🔧 功能全面：26 种 GitHub 操作，覆盖完整工作流
• ⚡ 快速：直接集成 GitHub CLI，并优化 JSON 响应
• 🧪 测试完善：75+ 个测试用例，确保可靠性
• 🛡️ 安全：利用现有的 GitHub CLI 认证

设置

1. 安装 GitHub CLI

   # macOS
   brew install gh
   
   # or download from 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 的详情” → 获取特定问题的信息
• “创建一个新问题，标题为 ‘Bug: Login fails’，描述为……”
• “关闭问题 #123，并添加评论 ‘Fixed in latest release’”

拉取请求管理

• “列出 kubernetes/kubernetes 仓库中的所有拉取请求”
• “显示 PR #456 的详情”
• “创建一个从我的 feature-branch 到 main 的拉取请求”
• “使用 squash 策略合并 PR #789”

CI/CD 和发布

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

文件操作

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

验证

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

• 是否已安装 Java 21+，并且已将其添加到 PATH 中
• 是否已安装并完成身份验证的 GitHub CLI（gh auth status）
• 配置中的 JAR 文件路径是否正确
• 是否已重启 Claude Desktop

测试服务

如需独立测试服务（不使用 Claude）：

./gradlew bootRun

服务将以 STDIO 模式启动，并等待 MCP 协议消息。不过，在正常使用时，应按照上文所示配置服务，使其由 Claude Desktop 自动运行。

开发命令

# Build the project and run all tests
./gradlew build

# Run tests (command syntax validation only)
./gradlew test

# Run tests including GitHub CLI integration tests
./gradlew test -Dtest.gh.integration=true

# Format code with Spotless (Google Java Format)
./gradlew spotlessApply

# Check code formatting without applying changes
./gradlew spotlessCheck

# Clean build artifacts
./gradlew clean

# Run the server locally for testing
./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 - 列出用户的仓库，可按可见性（public/private/internal）筛选
• searchRepositories - 搜索 GitHub 仓库
• getRepository - 获取详细的仓库信息
• getCommitHistory - 获取仓库提交历史，可配置数量上限
• listBranches - 列出仓库分支
• createBranch - 创建新分支

问题管理

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

拉取请求管理

• listPullRequests - 列出拉取请求
• getPullRequest - 获取 PR 详情
• createPullRequest - 创建新的拉取请求
• mergePullRequest - 合并 PR（merge/squash/rebase）
• closePullRequest - 关闭拉取请求
• commentOnPullRequest - 添加 PR 评论

工作流和 CI/CD

• listWorkflows - 列出仓库工作流
• listWorkflowRuns - 列出工作流运行记录，可进行筛选
• getWorkflowRun - 获取工作流运行详情

发布管理

• listReleases - 列出仓库发布版本
• getRelease - 获取发布版本详情
• createRelease - 创建新发布版本（可设置草稿/预发布选项）

文件和用户操作

• getFileContents - 获取仓库中的文件内容
• getMe - 获取已通过身份验证的用户详情

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

故障排除

常见问题

“gh: command not found”

• 从 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 Format 进行代码格式化

主要实现特性

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

许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。