GIT MCP Server

GIT MCP 服务

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

目录

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

概述

核心功能：

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

架构与组件

核心系统架构：

flowchart TB
    subgraph API["API Layer"]
        direction LR
        MCP["MCP Protocol"]
        Val["Validation"]

        MCP --> Val
    end

    subgraph Core["Core Services"]
        direction LR
        GitService["Git Service"]
        ErrorService["Error Service"]

        GitService <--> ErrorService
    end

    subgraph Resources["Resource Layer"]
        direction LR
        Repo["Repository Resources"]
        Diff["Diff Resources"]
        File["File Resources"]
        History["History Resources"]

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

    subgraph Tools["Tool Layer"]
        direction LR
        RepoTools["Repository Tools"]
        BranchTools["Branch Tools"]
        WorkdirTools["Working Directory Tools"]
        RemoteTools["Remote Tools"]
        AdvancedTools["Advanced Tools"]

        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

核心组件：

• MCP 服务：使用模型上下文协议 SDK 创建一个公开资源和工具的服务
• Git 服务：基于 simple-git 的抽象层，为 Git 操作提供简洁的接口
• 资源：通过 MCP 资源和一致的 URI 模板公开 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 使用 Model Context Protocol 通信，因此兼容任何 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           # Entry point
│   ├── server.ts          # MCP server implementation
│   ├── resources/         # Resource implementations
│   │   ├── descriptors.ts # Resource URI templates
│   │   ├── diff.ts        # Diff-related resources
│   │   ├── file.ts        # File-related resources
│   │   ├── history.ts     # History-related resources
│   │   ├── index.ts       # Resource registration
│   │   └── repository.ts  # Repository resources
│   ├── services/          # Service implementations
│   │   ├── error-service.ts # Error handling
│   │   └── git-service.ts   # Git operations abstraction
│   ├── tools/             # Tool implementations
│   │   ├── advanced.ts    # Advanced Git operations
│   │   ├── branch.ts      # Branch operations
│   │   ├── index.ts       # Tool registration
│   │   ├── remote.ts      # Remote operations
│   │   ├── repository.ts  # Repository operations
│   │   └── workdir.ts     # Working directory operations
│   ├── types/             # Type definitions
│   │   └── git.ts         # Git-related types
│   └── utils/             # Utility functions
│       └── validation.ts  # Input validation
└── scripts/               # Development scripts

工具

Git MCP Server 提供了一套全面的 Git 操作工具：

仓库操作

分支操作

工作目录操作

远程操作

高级操作

资源

Git MCP Server 通过标准 MCP 资源公开 Git 数据：

仓库资源

开发

构建和测试

# Build the project
npm run build

# Watch for changes
npm run watch

# Test with MCP inspector
npm run inspector

# Clean build artifacts
npm run clean

# Rebuild completely
npm run rebuild

许可证

Apache License 2.0 - 详情请参阅 LICENSE。