星战科技xingzhan.cloud
返回市场
GitHub-MCP-服务器

GitHub-MCP-服务器

作者：cyanheads8 星标更新：2025-07-23
安装使用来源：spider==github.com

项目介绍

🚨 本仓库已弃用。🚨

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

🚨 本仓库已弃用。🚨

GitHub MCP 服务器

TypeScript Model Context Protocol 版本 许可证 状态 GitHub

这是一个提供与 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 个人访问令牌

设置

  1. 克隆仓库：

    git clone https://github.com/cyanheads/github-mcp-server.git
cd github-mcp-server

  2. 安装依赖项：

    npm install

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

    GITHUB_TOKEN=your_github_personal_access_token
LOG_LEVEL=info
SERVER_NAME=github-mcp-server

  4. 构建项目：

    npm run build

  5. 启动服务器：

    node build/index.js

配置

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

环境变量描述默认值
GITHUB_TOKENGitHub 个人访问令牌（必需）-
LOG_LEVEL日志级别（debug, info, warn, error, fatal）info
SERVER_NAMEMCP 服务器名称github-mcp-server
SERVER_VERSIONMCP 服务器版本0.1.0
API_TIMEOUT_MSAPI 调用超时时间（毫秒）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 特定问题）
    • 系统错误（意外失败）
  • 详细日志：所有操作和错误的结构化日志

贡献

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

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

许可证

Apache 许可证 2.0

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