GitHub-MCP-服务器

Name: GitHub-MCP-服务器
Author: cyanheads

作者：cyanheads8 星标更新：2025-07-23

安装使用来源：spider==github.com

项目介绍

🚨 本仓库已弃用。🚨

请改用官方 GitHub MCP 服务器：https://github.com/github/github-mcp-server

🚨 本仓库已弃用。🚨

GitHub MCP 服务器

这是一个提供与 GitHub API 交互工具的 Model Context Protocol (MCP) 服务器。此服务器允许 LLM 代理通过标准化接口管理 GitHub 存储库、问题、拉取请求、分支、文件和发布。

概述

github-mcp-server 实现了 Model Context Protocol (MCP)，使 LLM 和外部系统之间能够通过以下方式进行标准化通信：

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

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

关键功能包括：

GitHub API 集成：安全无缝地集成 GitHub 的 REST API
全面的 GitHub 功能：完整管理存储库、分支、问题、拉取请求等
原子特征架构：维护良好的模块化代码结构
输入验证：使用 Zod 模式进行强大的验证
错误处理：一致的错误分类和报告
速率限制：内置的 GitHub API 速率限制处理
性能关注：优化的操作和响应格式

架构与组件

核心系统架构：

<details> <summary>点击展开 Mermaid 图表</summary>

flowchart TB
    subgraph API["API 层"]
        direction LR
        MCP["MCP 协议"]
        Val["验证"]
        Rate["速率限制"]

        MCP --> Val --> Rate
    end

    subgraph Features["功能模块"]
        direction LR
        Repo["存储库管理"]
        Branch["分支管理"]
        Issue["问题管理"]
        PR["拉取请求管理"]
        File["文件管理"]
        Release["发布管理"]

        Repo <--> Branch
        Repo <--> Issue
        Repo <--> PR
        Repo <--> File
        Branch <--> PR
    end

    subgraph Services["服务层"]
        direction LR
        GitHub["GitHub 服务"]
        Mapper["响应映射器"]
        RateLimiter["速率限制器"]

        GitHub <--> RateLimiter
        GitHub <--> Mapper
    end

    Rate --> Repo
    Rate --> Branch
    Rate --> Issue
    Rate --> PR
    Rate --> File
    Rate --> Release

    Repo --> GitHub
    Branch --> GitHub
    Issue --> GitHub
    PR --> GitHub
    File --> GitHub
    Release --> GitHub

    classDef layer fill:#2d3748,stroke:#4299e1,stroke-width:3px,rx:5,color:#fff
    classDef component fill:#1a202c,stroke:#a0aec0,stroke-width:2px,rx:3,color:#fff
    classDef api fill:#3182ce,stroke:#90cdf4,stroke-width:2px,rx:3,color:#fff
    classDef features fill:#319795,stroke:#81e6d9,stroke-width:2px,rx:3,color:#fff
    classDef services fill:#2f855a,stroke:#9ae6b4,stroke-width:2px,rx:3,color:#fff

    class API,Features,Services layer
    class MCP,Val,Rate api
    class Repo,Branch,Issue,PR,File,Release features
    class GitHub,Mapper,RateLimiter services

</details>

核心组件包括：

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
```

在项目根目录中创建一个 .env 文件，并添加您的 GitHub 令牌：

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`	日志级别（debug, info, warn, error, fatal）	info
`SERVER_NAME`	MCP 服务器名称	github-mcp-server
`SERVER_VERSION`	MCP 服务器版本	0.1.0
`API_TIMEOUT_MS`	API 调用超时时间（毫秒）	10000
`RATE_LIMITING_ENABLED`	是否启用速率限制	true
`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             // 应用程序配置
  /dependencyInjection       // 工具注册和 DI 容器
  /features                  // 按领域组织的功能模块
    /repositoryManagement
      /resources             // 读操作
      /modifications         // 写操作
    /branchManagement
    /issueManagement
    /pullRequestManagement
    /fileManagement
    /releaseManagement
  /services                  // 外部服务集成
    /githubAccess            // GitHub API 客户端和实用工具
  /types                     // 核心类型定义
  /utilities                 // 辅助函数和实用工具

每个功能域被分为：

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

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

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

工具

GitHub MCP 服务器提供了一整套与 GitHub 交互的工具：

存储库管理工具

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

分支管理工具

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

问题管理工具

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

拉取请求管理工具

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

文件管理工具

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

发布管理工具

工具	描述
`create_release`	创建一个新的发布<br>参数：`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 特定问题）
- 系统错误（意外失败）
详细日志：所有操作和错误的结构化日志

贡献

欢迎贡献！请随意提交拉取请求。

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

许可证

Apache 许可证 2.0

<div align="center"> 使用 Model Context Protocol 构建 </div>