AI导哈

GitHub集成服务器

一个基于Spring Boot的GitHub集成服务器，通过Model Context Protocol (MCP)为AI助手提供GitHub操作工具，支持仓库管理、问题跟踪、拉取请求管理等26种操作。

  • by kousen
  • Java
  • 本地部署
  • 8 星标
  • 更新于
在 GitHub 查看 kousen/gh_mcp_server

使用说明

GitHub MCP服务器

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

概述

此服务器实现了模型上下文协议，将GitHub操作作为MCP客户端可以使用的工具公开。它利用GitHub CLI(gh)执行各种GitHub操作，包括存储库管理、问题跟踪、拉取请求管理等。这为不需要Docker的官方GitHub MCP服务器提供了一种轻量级的替代方案。

Claude Desktop快速入门

要将此服务器与Claude Desktop一起使用，请将以下内容添加到您的Claude配置文件中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
视窗: %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命令行界面(gh) -必须安装并验证
  • Gradle -项目中包含的包装

为什么使用此MCP服务器？

  • 🚀 轻量级：无需Docker，纯Java实现
  • 🔧 全面的：26个GitHub操作，涵盖完整的工作流程
  • ⚡ 快速：通过优化JSON响应直接集成GitHub CLI
  • 🧪 测试良好：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桌面

    构建后，配置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后，您可以使用自然语言与GitHub进行交互：

库管理

  • “列出我的存储库” → 显示包含详细信息的存储库
  • “列出我的私有存储库” → 按可见性筛选（公共/私人/内部）
  • “搜索超过1000颗星的Spring Boot存储库”
  • “显示有关microsoft/vcode存储库的详细信息”
  • “从我的项目存储库中获取最后5个提交”
  • “我的项目存储库中存在哪些分支？”

问题跟踪

  • “列出我项目中的未决问题” → 列出当前未解决的问题
  • “显示问题#123详细信息” → 获取特定问题信息
  • “创建一个标题为“Bug：登录失败”的新问题，并附上描述…”
  • “关闭第123期并添加评论‘已在最新版本中修复’”

拉取请求管理

  • “列出kubernetes/kubernetes存储库中的所有pull请求”
  • “显示PR#456的详细信息”
  • “创建从我的功能分支到main的pull请求”
  • “使用挤压策略合并PR#789”

CI/CD及其发布

  • “显示此存储库中的所有工作流” → 列出GitHub操作
  • “最近工作流运行的状态如何？”
  • “列出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自动运行，如上所示。

开发命令

# 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 -使用可选的可见性过滤器（公共/私有/内部）列出用户的存储库
  • searchRepositories -搜索GitHub存储库
  • getRepository -获取详细的存储库信息
  • getCommitHistory -获取具有可配置限制的存储库提交历史记录
  • listBranches -列出存储库分支
  • createBranch -创建新分支

问题管理

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

拉取请求管理

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

工作流和CI/CD

  • listWorkflows -列出存储库工作流
  • listWorkflowRuns -列表工作流使用筛选运行
  • getWorkflowRun -获取工作流运行详细信息

发布管理

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

文件和用户操作

  • getFileContents -从存储库获取文件内容
  • getMe -获取经过身份验证的用户详细信息

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

故障排除

常见问题

“gh:找不到命令”

  • 从以下位置安装GitHub CLIhttps://cli.github.com/
  • 确保 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选项（自动使用最新版本）
    • 使用处理版本更新的部署脚本

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

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

配置管理

  • 将您的Claude Desktop配置保存在版本控制中
  • 记录生产中使用的特定JAR版本
  • 考虑在部署脚本中使用环境变量作为路径

技术栈

  • 弹簧靴3.5.0 -应用框架
  • 春季AI 1.0.0 -AI集成和MCP服务器功能
  • Java 21 -支持虚拟线程的编程语言
  • GitHub命令行界面 -GitHub API集成
  • Gradle -构建工具
  • 无瑕 -使用Google Java格式进行代码格式化

关键实施特征

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

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

相关 MCP