GitHub MCP 服务器

一个模型上下文协议 (MCP) 服务器，提供与 GitHub API 交互的工具。该服务器允许 LLM 代理通过标准化界面管理 GitHub 存储库、问题、拉取请求、分支、文件和发布。

概述

github-mcp-server 实现了模型上下文协议 (MCP)，通过以下方式实现 LLM 与外部系统之间的标准化通信：

客户端：Claude Desktop、IDE 和其他与 MCP 兼容的客户端
服务器：项目管理和协作的工具和资源
LLM 代理：利用以编程方式执行 GitHub 操作的能力的 AI 模型。

它充当 AI 模型和 GitHub API 之间的桥梁，提供一组遵循一致模式并处理身份验证、验证、错误处理和速率限制的明确定义的工具。

主要功能：

GitHub API 集成：与 GitHub 的 REST API 安全无缝集成
全面的 GitHub 功能：全面管理 repos、分支、问题、PR 等
原子特性架构：组织良好的模块化代码结构，易于维护
输入验证：对所有操作进行 Zod 模式的可靠验证
错误处理：一致的错误分类和报告
速率限制：内置 GitHub API 速率限制处理
性能重点：优化操作和响应格式

架构与组件

核心系统架构：

核心组件：

MCP 协议层：处理与 AI 助手的通信
验证层：通过模式验证确保数据完整性
GitHub 服务：与 GitHub REST API 的核心集成
速率限制器：防止 API 速率限制耗尽
功能模块：特定领域的 GitHub 操作
错误处理：全面的错误处理和日志系统

特征

存储库管理

创建、列出、获取：创建新的存储库、列出用户存储库以及获取详细的存储库信息
验证和配置：验证存储库设置并管理配置选项

分支机构管理

创建、删除、列出：通过安全验证完成分支生命周期管理
受保护分支支持：受保护分支的过滤和操作

问题管理

创建和列表：使用标签创建详细问题并使用过滤选项列出问题
状态跟踪：按问题状态过滤（打开、关闭、全部）

拉取请求管理

创建、更新、合并、列出：完整的拉取请求生命周期管理
评审和评论集成：向拉取请求添加评审和评论
合并选项：支持不同的合并策略（合并、压缩、变基）

文件管理

创建和更新文件：使用提交消息添加和修改存储库内容
Base64 编码支持：处理文本和二进制文件内容

发布管理

创建发布：使用可自定义的选项创建标记的发布
草稿和预发布支持：支持草稿和预发布工作流程

安装

先决条件

Node.js（v16 或更高版本）
具有适当权限的 GitHub 个人访问令牌

设置

克隆存储库：
git clone https://github.com/cyanheads/github-mcp-server.git cd github-mcp-server
安装依赖项：
npm install
使用您的 GitHub 令牌在项目根目录中创建一个.env文件：
GITHUB_TOKEN=your_github_personal_access_token LOG_LEVEL=info SERVER_NAME=github-mcp-server
构建项目：
npm run build
启动服务器：
node build/index.js

配置

可以通过环境变量配置服务器：

环境变量	描述	默认
`GITHUB_TOKEN`	GitHub 个人访问令牌（必需）	-
`LOG_LEVEL`	日志级别（调试、信息、警告、错误、致命）	信息
`SERVER_NAME`	MCP 服务器名称	github-mcp-服务器
`SERVER_VERSION`	MCP 服务器版本	0.1.0
`API_TIMEOUT_MS`	API 调用超时（以毫秒为单位）	10000
`RATE_LIMITING_ENABLED`	是否启用速率限制	真的
`RATE_LIMITING_MIN_REMAINING`	限制前剩余的最少请求数	100
`RATE_LIMITING_RESET_BUFFER_MS`	添加到速率限制重置时间的时间缓冲区	5000

MCP 客户端设置

添加到您的 MCP 客户端设置：

{
  "mcpServers": {
    "github": {
      "command": "node",
      "args": ["/path/to/github-mcp-server/build/index.js"],
      "env": {
        "GITHUB_TOKEN": "your_github_personal_access_token",
        "LOG_LEVEL": "info",
        "SERVER_NAME": "github-mcp-server"
      }
    }
  }
}

项目结构

该项目遵循面向原子特征的架构模式：

/src
  /configuration             // Application configuration
  /dependencyInjection       // Tool registry and DI container
  /features                  // Feature modules organized by domain
    /repositoryManagement
      /resources             // Read operations
      /modifications         // Write operations
    /branchManagement
    /issueManagement
    /pullRequestManagement
    /fileManagement
    /releaseManagement
  /services                  // External service integrations
    /githubAccess            // GitHub API client and utilities
  /types                     // Core type definitions
  /utilities                 // Helper functions and utilities

每个特征域分为：

资源：不修改数据的读取操作
修改：创建、更新或删除数据的写入操作

每个操作都包含在其自己的目录中：

操作实施文件
类型定义文件
导出索引文件

工具

GitHub MCP Server 提供了一套全面的与 GitHub 交互的工具：

存储库管理工具

工具	描述
`get_repository`	获取特定存储库的详细信息参数： `owner` ， `repo`
`list_repositories`	列出经过身份验证的用户的存储库参数： `type` （可选）、 `sort` （可选）
`create_repository`	创建一个新的 GitHub 存储库参数： `name` 、 `description` （可选）、 `private` （可选）

分支管理工具

工具	描述
`list_branches`	列出存储库中的分支参数： `owner` 、 `repo` 、 `protected` （可选）、 `per_page` （可选）
`create_branch`	创建新分支参数： `owner` , `repo` , `branch` , `sha`
`delete_branch`	删除分支参数： `owner` , `repo` , `branch`

问题管理工具

工具	描述
`create_issue`	在存储库中创建新问题参数： `owner` ， `repo` ， `title` ， `body` （可选）， `labels` （可选）
`list_issues`	列出存储库中的问题参数： `owner` 、 `repo` 、 `state` （可选）、 `labels` （可选）

拉取请求管理工具

工具	描述
`create_pull_request`	创建一个新的拉取请求参数： `owner` ， `repo` ， `title` ， `head` ， `base` ， `body` （可选）
`merge_pull_request`	合并拉取请求参数： `owner` ， `repo` ， `pull_number` ， `commit_title` （可选）， `commit_message` （可选）， `merge_method` （可选）
`update_pull_request`	更新现有的拉取请求参数： `owner` 、 `repo` 、 `pull_number` 、 `title` （可选）、 `body` （可选）、 `state` （可选）、 `base` （可选）、 `maintainer_can_modify` （可选）
`list_pull_requests`	列出存储库中的拉取请求参数： `owner` 、 `repo` 、 `state` （可选）、 `head` （可选）、 `base` （可选）、 `sort` （可选）、 `direction` （可选）

文件管理工具

工具	描述
`update_file`	在存储库中创建或更新文件参数： `owner` ， `repo` ， `path` ， `message` ， `content` ， `sha` （可选）， `branch` （可选）

发布管理工具

工具	描述
`create_release`	创建一个新的版本参数： `owner` ， `repo` ， `tag_name` ， `name` （可选）， `body` （可选）， `draft` （可选）， `prerelease` （可选）

发展

项目结构

该项目遵循严格的命名约定和目录结构：

文件命名： action.entity.type.ts （例如， create.repository.operation.ts ）
每个模块都有明确定义的目的
类型与其实现位于同一位置
所有导出都通过索引文件集中

脚本

npm run build构建项目
npm run watch - 观察变化并重建
npm run inspector - 运行 MCP 检查器工具
npm run clean - 清理构建产物
npm run rebuild清理并重建项目
npm run tree - 生成目录树表示

错误处理

服务器实现了全面的错误处理策略：

标准化错误对象：一致的错误格式和分类
输入验证：使用 Zod 模式进行预验证
速率限制保护：自动处理 GitHub API 速率限制
错误类别：
- 网络错误（连接问题）
- 身份验证错误（令牌问题）
- 验证错误（无效输入）
- GitHub API 错误（API 特定问题）
- 系统错误（意外故障）
详细日志记录：所有操作和错误的结构化日志记录

贡献

欢迎贡献代码！欢迎提交 Pull 请求。

分叉存储库
创建你的功能分支（ git checkout -b feature/amazing-feature ）
提交您的更改（ git commit -m 'Add some amazing feature' ）
推送到分支（ git push origin feature/amazing-feature ）
打开拉取请求

执照

Apache 许可证 2.0

Integrations

GitHub MCP 服务器

目录

概述

架构与组件

特征

存储库管理

分支机构管理

问题管理

拉取请求管理

文件管理

发布管理

安装

先决条件

设置

配置

MCP 客户端设置

项目结构

工具

存储库管理工具

分支管理工具

问题管理工具

拉取请求管理工具

文件管理工具

发布管理工具

发展

项目结构

脚本

错误处理

贡献

执照