GitHub MCP Server

🔗 在MCP市场上查看 <br /> 🔗 在MCP注册表中查看 <br /> 📦 在npm上可用

这是一个提供29个Git操作+11个工作流组合的模型上下文协议（MCP）服务器，适用于AI助手和开发者。该服务器通过标准化接口暴露全面的Git仓库管理功能，使AI模型和开发者能够安全地管理复杂的版本控制工作流程。

🚀 快速安装

方案1：从npm安装（推荐）

# 从npm安装
npm install -g @0xshariq/github-mcp-server

# 测试安装
gstatus
glist

方案2：符号链接（替代方案 - 不使用包管理器）

# 克隆并设置
git clone https://github.com/0xshariq/github-mcp-server.git
cd github-mcp-server
npm install && npm run build

# 创建符号链接（跨平台）
./setup-symbolic.sh --user          # 用户安装
# 或者
sudo ./setup-symbolic.sh           # 系统范围（Linux/macOS）

# 测试安装
gstatus
glist

🛠️ 遇到问题？ 如果安装后命令无法运行，请参阅我们的**完整故障排除指南**，以解决包括“命令未找到”错误、路径冲突、PNPM问题以及符号链接替代方案在内的所有常见问题。

🎯 关于

GitHub MCP Server 将AI助手与Git仓库连接起来，并提供了强大的开发者生产力工具。它提供：

• 通过标准化MCP接口进行的安全Git操作（29个操作）
• 完整的版本控制能力，包括高级操作（标签、合并、变基、樱桃挑选、归责、二分查找）
• 31个工作流组合，以增强开发者生产力
• 高级开发者工具（备份、清理、工作流自动化）
• 错误处理和验证，防止常见的Git错误
• 直接集成VS Code和AI助手如GitHub Copilot
• 命令行界面包装器，用于终端访问和自动化

🚀 功能概述

此服务器通过两个主要类别提供全面的Git仓库管理：

📁 基本Git操作（17个操作）

日常必需的Git命令组织在bin/basic/中 - 详细文档见**基本操作指南**。

• 文件管理：添加、移除暂存区中的文件
• 仓库信息：状态、历史、差异
• 提交操作：创建提交、推送、拉取
• 分支管理：创建、切换分支
• 远程管理：添加、移除、配置远程
• 暂存操作：临时保存更改
• 重置操作：仓库状态管理

🚀 高级Git操作（12个操作）

复杂的工作流和自动化在bin/advanced/中 - 详细文档见**高级工作流指南**。

• 工作流组合：完整的流程（添加→提交→推送）、快速提交、同步操作
• 开发工具：智能开发工作流、备份系统
• 高级Git特性：标签、合并、变基、樱桃挑选、归责、二分查找
• 维护与安全：仓库清理、优化、备份管理
• 专业工作流：发布管理、热修复程序、团队协作

🛠️ 安装

详情请参阅markdown/INSTALLATION.md，获取Windows、macOS、WSL及所有平台的详细安装指南。

🏗️ 项目结构与架构

GitHub MCP Server 组织清晰，便于逐步学习：

github-mcp-server/
├── src/
│   ├── index.ts              # MCP服务器（29个工具注册，模式定义）
│   └── github.ts             # Git操作引擎（全部29个实现）
├── bin/
│   ├── basic/                # 📁 17个基本Git操作
│   │   ├── README.md         # 全面的基本操作指南
│   │   ├── gadd.js           # 添加文件（git add）
│   │   ├── gcommit.js        # 创建提交（git commit）
│   │   ├── gpush.js          # 推送更改（git push）
│   │   ├── gpull.js          # 拉取更改（git pull）
│   │   ├── gstatus.js        # 仓库状态（git status）
│   │   ├── gbranch.js        # 分支管理（git branch）
│   │   ├── gcheckout.js      # 切换分支（git checkout）
│   │   ├── glog.js           # 提交历史（git log）
│   │   ├── gdiff.js          # 显示差异（git diff）
│   │   ├── gstash.js         # 暂存操作（git stash）
│   │   ├── gpop.js           # 应用暂存（git stash pop）
│   │   ├── greset.js         # 重置操作（git reset）
│   │   ├── gclone.js         # 克隆仓库（git clone）
│   │   ├── gremote.js        # 远程管理（git remote）
│   │   └── ginit.js          # 初始化仓库（git init）
│   └── advanced/             # 🚀 13个高级工作流及自动化
│       ├── README.md         # 全面的高级工作流指南
│       ├── gflow.js          # 完整的工作流（添加→提交→推送）
│       ├── gquick.js         # 快速提交工作流
│       ├── gsync.js          # 同步工作流（拉取→推送）
│       ├── gdev.js           # 开发会话管理
│       ├── gworkflow.js      # 专业工作流组合
│       ├── gfix.js           # 智能修复和补丁工作流
│       ├── gfresh.js         # 新开始工作流
│       ├── gbackup.js        # 备份和安全操作
│       ├── gclean.js         # 仓库清理和优化
│       ├── gsave.js          # 保存和保留工作流
│       ├── glist.js          # 工具发现和帮助系统
│       ├── grelease.js       # 发布管理工作流
│       └── common.js         # 共享实用工具和辅助工具
├── markdown/
│   ├── INSTALLATION.md      # 详细的安装指南
│   ├── DEPLOY.md            # 生产部署指南
│   ├── DOCKER.md            # Docker设置和部署指南
│   └── QUICK_REFERENCES.md  # 复制粘贴命令参考
├── mcp-cli.js               # 增强的CLI包装器（按结构组织）
├── package.json             # 项目配置及npm脚本
├── tsconfig.json            # TypeScript配置
└── README.md                # 这份综合指南

📖 文档结构

• bin/basic/README.md - 17个基本Git操作的完整指南
• bin/advanced/README.md - 全面的高级工作流文档
• markdown/INSTALLATION.md - 所有平台的逐步安装指南
• markdown/TROUBLESHOOTING.md - 🛠️ 完整的故障排除指南 - 解决所有常见问题的方法
• markdown/MCP_UNIVERSAL_CONFIG.md - 所有LLM客户端的通用MCP配置
• markdown/QUICK_REFERENCES.md - 复制粘贴命令的快速参考
• markdown/DOCKER.md - Docker设置、部署和容器化
• markdown/DEPLOY.md - 生产部署和托管策略

🔧 技术架构

📡 MCP服务器核心（src/index.ts）

• 29个工具注册，带有完整的JSON模式
• 增强的元数据，带有操作跟踪和性能监控
• 输入验证，使用Zod模式确保类型安全
• 错误处理管道，带有超时保护和有意义的消息
• 跨平台兼容性，带有环境规范化

⚙️ Git操作引擎（src/github.ts）

• 全面实现所有29个Git操作
• 安全性功能 - 命令注入预防和输入净化
• 增强的错误处理，带有常见场景的上下文感知消息
• 性能监控 - 操作持续时间跟踪和日志记录
• 安全检查 - 仓库验证和文件存在验证

🖥️ 增强的CLI系统

• 智能组织 - 工具按基本和高级操作分类
• 目录感知的帮助 - 引用特定的README文件以获得详细指导
• 逐步学习 - 从基本到高级操作的明确路径
• 工具发现 - 带有类别过滤的增强glist命令

🛡️ 错误处理与安全

• 🔍 仓库验证：确保目录是一个有效的Git仓库
• 📁 文件存在检查：在执行Git操作前验证文件的存在
• ⏱️ 超时保护：操作的30秒超时
• 🚫 输入净化：防止命令注入
• 📝 详细的错误消息：清晰、可操作的错误描述

🛠️ 故障排除

遇到安装或命令无法运行的问题吗？我们已经为您准备好了！我们的综合故障排除指南涵盖了所有常见问题的解决方案：

🚨 最常见的问题及快速修复

问题	快速解决方案
💥 命令未找到错误	unset command_not_found_handle
📁 PNPM路径冲突	从全局目录中删除/5/
🔗 命令显示帮助而不是执行	更新包装脚本以传递命令名称
🚫 权限被拒绝	chmod +x ~/.local/share/pnpm/g*

👉 有关详细解决方案、逐步修复方法和诊断工具，请参阅我们的完整故障排除指南

🆘 快速诊断

# 测试命令是否正常工作
gstatus                    # 应该显示仓库状态
env gstatus               # 如果上面失败，尝试这个
which gstatus             # 应该显示命令路径

# 如果仍然有问题，请参阅TROUBLESHOOTING.md以获取完整解决方案

许可证

ISC许可证

作者

为支持模型上下文协议的AI助手而创建。