GIT MCP 服务器

一个模型上下文协议 (MCP) 服务器，提供与 Git 仓库交互的工具。该服务器允许 AI 助手和 LLM 代理通过标准化的接口管理仓库、分支、提交和文件，而无需直接的文件系统或命令行访问。它将 Git 操作作为 MCP 资源和工具公开，同时保持适当的安全边界。

目录

• 概述
  • 架构 & 组件
• 特性
  • 资源访问
  • Git 操作
• 安装
  • 先决条件
  • 从 NPM 安装
  • 从源码安装
• 使用
  • 运行服务器
  • 与 Claude 集成
  • 与其他 MCP 客户端集成
• 项目结构
• 工具
  • 仓库操作
  • 分支操作
  • 工作目录操作
  • 远程操作
  • 高级操作
• 资源
  • 仓库资源
• 开发
  • 构建和测试
• 许可证

概述

主要功能：

• 仓库管理：初始化、克隆和检查仓库状态
• 分支操作：创建、列出、检出、删除和合并分支
• 工作目录：暂存文件、提交更改、创建差异
• 远程操作：添加远程仓库、抓取、拉取、推送
• 高级 Git 命令：管理标签、储藏更改、拣选提交、变基

架构 & 组件

核心系统架构：

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

flowchart TB
    subgraph API["API 层"]
        direction LR
        MCP["MCP 协议"]
        Val["验证"]

        MCP --> Val
    end

    subgraph Core["核心服务"]
        direction LR
        GitService["Git 服务"]
        ErrorService["错误服务"]

        GitService <--> ErrorService
    end

    subgraph Resources["资源层"]
        direction LR
        Repo["仓库资源"]
        Diff["差异资源"]
        File["文件资源"]
        History["历史资源"]

        Repo <--> Diff
        Repo <--> File
        Repo <--> History
    end

    subgraph Tools["工具层"]
        direction LR
        RepoTools["仓库工具"]
        BranchTools["分支工具"]
        WorkdirTools["工作目录工具"]
        RemoteTools["远程工具"]
        AdvancedTools["高级工具"]

        RepoTools <--> BranchTools
        BranchTools <--> WorkdirTools
        WorkdirTools <--> RemoteTools
        RemoteTools <--> AdvancedTools
    end

    Val --> GitService
    GitService --> Resources
    GitService --> Tools

    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 core fill:#319795,stroke:#81e6d9,stroke-width:2px,rx:3,color:#fff
    classDef resource fill:#2f855a,stroke:#9ae6b4,stroke-width:2px,rx:3,color:#fff
    classDef tool fill:#805ad5,stroke:#d6bcfa,stroke-width:2px,rx:3,color:#fff

    class API,Core,Resources,Tools layer
    class MCP,Val api
    class GitService,ErrorService core
    class Repo,Diff,File,History resource
    class RepoTools,BranchTools,WorkdirTools,RemoteTools,AdvancedTools tool

</details>

核心组件：

• MCP 服务器：使用模型上下文协议 SDK 创建一个公开资源和工具的服务器
• Git 服务：simple-git 之上的抽象层，为 Git 操作提供清晰的接口
• 资源：通过具有一致 URI 模板的 MCP 资源公开 Git 数据
• 工具：通过具有明确定义的模式的 MCP 工具公开 Git 操作
• 错误处理：标准化的错误处理和报告

特性

资源访问

通过 MCP 资源公开 Git 仓库信息：

• 仓库信息：访问基本的 Git 仓库信息，包括当前分支、状态和引用详细信息
• 仓库分支：列出仓库中的所有分支，并带有当前分支指示器
• 仓库远程仓库：列出所有配置的远程仓库及其 URL
• 仓库标签：列出仓库中的所有标签及其引用
• 文件内容：访问给定 Git 引用处特定文件的内容
• 目录列表：查看特定路径和引用处的文件和目录列表
• 差异：获取引用之间、未暂存的更改或已暂存的更改之间的差异
• 提交历史：查看详细的提交日志，包括作者、日期和消息信息
• 文件追溯：查看逐行归属，显示哪个提交最后修改了每一行
• 提交详情：访问有关特定提交的详细信息，包括差异更改

Git 操作

通过 MCP 工具执行 Git 命令：

• 仓库操作：初始化仓库、从远程仓库克隆、检查仓库状态
• 分支操作：创建分支、列出分支、检出、删除分支、合并
• 工作目录操作：暂存文件、取消暂存文件、提交更改、创建差异
• 远程操作：添加远程仓库、列出远程仓库、抓取、拉取、推送
• 高级操作：管理标签、储藏更改、拣选提交、变基分支、重置、清理

安装

先决条件

• Node.js 16 或更高版本
• Git 已安装并在 PATH 中可用

从 NPM 安装

npm install -g git-mcp-server

从源码安装

git clone https://github.com/cyanheads/git-mcp-server.git
cd git-mcp-server
npm install
npm run build

使用

运行服务器

git-mcp-server

服务器通过 stdin/stdout 使用模型上下文协议进行通信，使其与任何 MCP 客户端兼容。

与 Claude 集成

添加到您的 Claude 配置文件：

{
  "mcpServers": {
    "git": {
      "command": "git-mcp-server",
      "args": [],
      "env": {},
      "disabled": false
    }
  }
}

与其他 MCP 客户端集成

使用 MCP 检查器测试服务器：

npx @modelcontextprotocol/inspector git-mcp-server

项目结构

代码库遵循模块化结构：

git-mcp-server/
├── src/
│   ├── index.ts           # 入口点
│   ├── server.ts          # MCP 服务器实现
│   ├── resources/         # 资源实现
│   │   ├── descriptors.ts # 资源 URI 模板
│   │   ├── diff.ts        # 与差异相关的资源
│   │   ├── file.ts        # 与文件相关的资源
│   │   ├── history.ts     # 与历史相关的资源
│   │   ├── index.ts       # 资源注册
│   │   └── repository.ts  # 仓库资源
│   ├── services/          # 服务实现
│   │   ├── error-service.ts # 错误处理
│   │   └── git-service.ts   # Git 操作抽象
│   ├── tools/             # 工具实现
│   │   ├── advanced.ts    # 高级 Git 操作
│   │   ├── branch.ts      # 分支操作
│   │   ├── index.ts       # 工具注册
│   │   ├── remote.ts      # 远程操作
│   │   ├── repository.ts  # 仓库操作
│   │   └── workdir.ts     # 工作目录操作
│   ├── types/             # 类型定义
│   │   └── git.ts         # 与 Git 相关的类型
│   └── utils/             # 实用函数
│       └── validation.ts  # 输入验证
└── scripts/               # 开发脚本

工具

Git MCP 服务器提供了一套全面的 Git 操作工具：

仓库操作

工具	描述
git_init	在指定路径初始化一个新的 Git 仓库，并提供裸仓库的选项。
git_clone	从远程 URL 克隆一个 Git 仓库到本地路径，并提供分支和深度选项。
git_status	获取 Git 仓库的当前状态，包括工作目录和暂存区的更改。

分支操作

工具	描述
git_branch_list	列出仓库中的所有分支，并提供包含远程分支的选项。
git_branch_create	创建一个新分支，并提供指定起始点和自动检出的选项。
git_checkout	检出一个分支、标签或提交，并提供在检出期间创建新分支的选项。
git_branch_delete	删除一个分支，并提供强制删除未合并分支的选项。
git_merge	将一个分支合并到当前分支，并提供可自定义的提交消息和合并策略。

工作目录操作

工具	描述
git_add	暂存文件以进行提交，并支持单个文件或整个目录。
git_reset	从暂存区取消暂存文件，并提供特定文件或所有已暂存更改的选项。
git_commit	提交已暂存的更改，并提供可自定义的提交消息、作者信息和修改选项。
git_diff_unstaged	获取工作目录中所有未暂存更改的差异，并提供特定文件的选项。
git_diff_staged	获取索引中所有已暂存更改的差异，并提供特定文件的选项。
git_reset_commit	将仓库重置为特定引用，并提供 hard、soft 或 mixed 模式的选项。
git_clean	从工作树中删除未跟踪的文件，并提供目录和强制清理的选项。

远程操作

工具	描述
git_remote_add	添加一个具有名称和 URL 的新远程仓库。
git_remote_list	列出所有配置的远程仓库及其 URL。
git_fetch	从远程仓库抓取更新，并提供特定分支的选项。
git_pull	从远程仓库拉取更改，并提供变基策略的选项。
git_push	将本地更改推送到远程仓库，并提供强制推送和上游跟踪的选项。

高级操作

工具	描述
git_tag_create	创建一个新标签，并提供带有消息的带注释标签的选项。
git_tag_list	列出仓库中的所有标签及其引用。
git_stash_create	储藏工作目录中的更改，并提供未跟踪文件和描述的选项。
git_stash_list	列出仓库中的所有储藏及其描述。
git_stash_apply	应用一个储藏的更改，而不将其从储藏列表中删除。
git_stash_pop	应用一个储藏的更改，并将其从储藏列表中删除。
git_cherry_pick	将特定提交中的更改应用到当前分支。
git_rebase	将当前分支变基到另一个分支，并提供交互模式选项。
git_log	获取提交历史，并提供可自定义的输出格式和深度。
git_show	显示有关特定提交的详细信息，包括差异更改。

资源

Git MCP 服务器通过标准 MCP 资源公开 Git 数据：

仓库资源

资源	描述
git://repo/{repoPath}/info	基本的 Git 仓库信息，包括当前分支、状态和引用详细信息
git://repo/{repoPath}/branches	仓库中所有分支的列表，并带有当前分支指示器
git://repo/{repoPath}/remotes	所有配置的远程仓库及其 URL 的列表
git://repo/{repoPath}/tags	仓库中所有标签及其引用的列表
git://repo/{repoPath}/file/{filePath}?ref={ref}	返回给定 Git 引用处特定文件的内容
git://repo/{repoPath}/ls/{dirPath}?ref={ref}	返回特定路径和引用处的文件和目录列表
git://repo/{repoPath}/diff/{fromRef}/{toRef}?path={path}	返回两个 Git 引用（提交、分支、标签）之间的差异
git://repo/{repoPath}/diff-unstaged?path={path}	返回工作目录中所有未暂存更改的差异
git://repo/{repoPath}/diff-staged?path={path}	返回索引中所有已暂存更改的差异
git://repo/{repoPath}/log?maxCount={maxCount}&file={file}	返回带有作者、日期和消息详细信息的提交历史日志
git://repo/{repoPath}/blame/{filePath}	返回逐行归属，显示哪个提交最后修改了每一行
git://repo/{repoPath}/commit/{commitHash}	返回有关特定提交的详细信息，包括差异更改

开发

构建和测试

# 构建项目
npm run build

# 监听更改
npm run watch

# 使用 MCP 检查器进行测试
npm run inspector

# 清理构建工件
npm run clean

# 完全重建
npm run rebuild

许可证

Apache License 2.0 - 有关详细信息，请参阅 LICENSE。

---

<div align="center"> 使用模型上下文协议构建 </div>