Git MCP 服务器

一个提供与 Git 仓库交互工具的 MCP（模型上下文协议）服务器。通过 MCP 标准，使 LLMs 和 AI 代理能够执行 Git 操作，如克隆、提交、推送、拉取、分支、差异、日志、状态等。

基于 cyanheads/mcp-ts-template，该服务器遵循模块化架构：

开发者注意：此仓库包含一个 .clinerules 文件，作为开发者的速查表，为您的 LLM 编码代理提供代码库模式、文件位置和代码片段的快速参考。

目录

| 概述 | 功能 | 安装 |

| 配置 | 项目结构 |

| 工具 | 资源 | 开发 | 许可证 |

概述

为您的 AI 代理和开发工具提供无缝的 Git 集成！

Git MCP 服务器充当桥梁，允许理解模型上下文协议（MCP）的应用程序（MCP 客户端）——如高级 AI 助手（LLMs）、IDE 扩展或自定义脚本——直接且安全地与本地 Git 仓库交互。

您的工具可以利用此服务器，而不是复杂的脚本或手动 CLI：

• 自动化 Git 工作流：克隆仓库、创建分支、暂存更改、提交工作、推送更新以及以编程方式管理标签。
• 获取仓库洞察：检查状态、查看日志、差异更改并检查 Git 对象，而无需离开主机应用程序。
• 将 Git 集成到 AI 驱动的开发中：使 LLMs 能够管理版本控制作为其编码或重构任务的一部分。

基于强大的 mcp-ts-template，该服务器通过 MCP 标准提供了一种标准化、安全且高效的方式来暴露 Git 功能。它通过使用 Node.js 的 child_process 模块安全地执行系统上安装的标准 git 命令行工具来实现这一点，确保兼容性并充分利用 Git 的全部功能。

功能

核心工具（来自模板）

利用 mcp-ts-template 提供的强大工具：

• 日志记录：结构化、可配置的日志记录（文件轮换、控制台、MCP 通知）和敏感数据脱敏。
• 错误处理：集中式错误处理、标准化错误类型（McpError）和自动日志记录。
• 配置：环境变量加载（dotenv）。
• 输入验证/清理：使用 zod 进行模式验证和自定义清理逻辑（对路径至关重要）。
• 请求上下文：通过唯一请求 ID 跟踪和关联操作。
• 类型安全：由 TypeScript 和 Zod 模式强制执行的强类型。
• HTTP 传输选项：内置 Express 服务器，支持 SSE、会话管理和 CORS。

Git 操作

• 直接 Git CLI 执行：通过 Node.js child_process 安全地执行标准 git 命令行工具与 Git 交互，确保完全兼容性和访问 Git 的功能。
• 全面的命令覆盖：将广泛的 Git 命令暴露为 MCP 工具（参见 工具 部分）。
• 仓库交互：支持状态检查、分支、暂存、提交、获取、拉取、推送、差异、日志、重置、标签等。
• 工作目录管理：允许设置和清除会话特定的工作目录，以在多个 Git 操作之间保持上下文持久性。
• 安全功能：包括检查并要求对潜在破坏性操作（如 git clean 和 git reset --hard）进行显式确认。
• 提交签名：支持 GPG 或 SSH 签名以验证提交，通过 GIT_SIGN_COMMITS 环境变量和服务器端 Git 配置控制。包括一个可选工具参数，以便在签名失败时回退到未签名的提交。

安装

先决条件

• Node.js (>=18.0.0)
• npm（随 Node.js 一起安装）
• Git 已安装并可在系统 PATH 中访问。

通过 npm 安装

1. 全局安装包：

   npm install @cyanheads/git-mcp-server
   

从源代码安装

1. 克隆仓库：

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

2. 安装依赖：

   npm install
   

3. 构建项目：

   npm run build（或 `npm run rebuild`）
   

   这将 TypeScript 代码编译为 JavaScript 到 dist/ 目录，并使入口点可执行。

配置

环境变量

使用环境变量配置服务器。在项目根目录中创建 .env 文件（从 .env.example 复制）或在环境中设置它们。

MCP 客户端设置

添加到您的 MCP 客户端设置（例如，cline_mcp_settings.json）：

{
  "mcpServers": {
    "git-mcp-server": {
      // 使用描述性名称
      "command": "node", // 使用 node 运行脚本
      "args": ["/path/to/your/git-mcp-server/dist/index.js"], // 构建入口点的绝对路径
      "env": {
        // "MCP_TRANSPORT_TYPE": "http", // 可选：如果使用 http
        // "MCP_HTTP_PORT": "3010",     // 可选：如果使用 http 且非默认端口
        // "GIT_SIGN_COMMITS": "true"   // 可选：如果服务器配置了，则启用提交签名尝试
      },
      "disabled": false,
      "autoApprove": [] // 如果需要，配置自动批准规则
    }
  }
}

注意：您可以查看 mcp.json 以获取包含 Git MCP 服务器的示例 MCP 客户端配置文件。

项目结构

代码库在 src/ 目录中遵循模块化结构：

src/
├── index.ts           # 入口点：初始化和启动服务器
├── config/            # 配置加载（环境变量，包信息）
│   └── index.ts
├── mcp-server/        # 核心 MCP 服务器逻辑和能力注册
│   ├── server.ts      # 服务器设置，能力注册
│   ├── transports/    # 传输处理（stdio, http）
│   ├── resources/     # MCP 资源实现（当前无）
│   └── tools/         # MCP 工具实现（按工具子目录）
├── types-global/      # 共享的 TypeScript 类型定义
└── utils/             # 通用工具函数（日志记录器，错误处理程序等）

有关详细文件树，请运行 npm run tree 或查看 docs/tree.md。

工具

Git MCP 服务器提供了一套用于与 Git 仓库交互的工具，可通过模型上下文协议调用。

注意：大多数工具的 path 参数默认为通过 git_set_working_dir 设置的会话工作目录。

资源

此版本（v2.0.14）未实现 MCP 资源。

此版本专注于基于最新 mcp-ts-template 和 MCP SDK v1.12.0 重构的 Git 工具实现。在此次重大更新期间，之前可用的资源能力已被暂时移除。

如果您需要 MCP 资源访问（例如，通过服务器直接读取文件内容），请使用稳定的 v1.2.4 版本。

未来的开发可能会在后续版本中重新引入资源能力。

注意：此版本（v2.0.0）专注于基于最新 MCP SDK 重构和更新核心 Git 工具。此版本未实现 MCP 资源能力。对于资源访问，请使用 v1.2.4。

开发

构建和测试

# 构建项目（将 TS 编译为 JS 到 dist/ 并使可执行）
npm run build

# 使用 MCP 检查器工具本地测试服务器（stdio 传输）
npm run inspector

# 使用 MCP 检查器工具本地测试服务器（http 传输）
npm run inspector:http

# 清理构建工件（运行 scripts/clean.ts）
npm run clean

# 生成文件树表示以用于文档（运行 scripts/tree.ts）
npm run tree

# 清理构建工件然后重新构建项目
npm run rebuild

# 使用 stdio 启动服务器（默认）
npm start
# 或显式：
npm run start:stdio

# 使用 HTTP 传输启动服务器
npm run start:http

许可证

此项目根据 Apache 许可证 2.0 授权 - 详情请参阅 LICENSE 文件。