Git

mcp-server-git：Git MCP 服务

概述

用于与 Git 仓库交互和自动化操作的模型上下文协议服务。此服务通过大语言模型提供读取、搜索和操作 Git 仓库的工具。

源代码：https://github.com/modelcontextprotocol/servers/tree/main/src/git

需要 MCP Python SDK 2.x（mcp>=2.3,<3）。此服务基于 SDK 的高级 MCPServer 构建：每个工具都是一个类型化的 Python 函数，SDK 会根据函数签名推导输入架构。

请注意，mcp-server-git 目前仍处于早期开发阶段。随着我们持续开发和改进此服务，功能和可用工具可能会发生变化并有所扩展。

工具

1. git_status

   • 显示工作树状态
   • 输入：
     • repo_path（string）：Git 仓库路径
   • 返回：以文本形式输出当前工作目录状态

2. git_diff_unstaged

   • 显示工作目录中尚未暂存的更改
   • 输入：
     • repo_path（string）：Git 仓库路径
     • context_lines（number，可选）：要显示的上下文行数（默认值：3）
   • 返回：未暂存更改的差异输出

3. git_diff_staged

   • 显示已暂存、待提交的更改
   • 输入：
     • repo_path（string）：Git 仓库路径
     • context_lines（number，可选）：要显示的上下文行数（默认值：3）
   • 返回：已暂存更改的差异输出

4. git_diff

   • 显示分支或提交之间的差异
   • 输入：
     • repo_path（string）：Git 仓库路径
     • target（string）：要进行比较的目标分支或提交
     • context_lines（number，可选）：要显示的上下文行数（默认值：3）
   • 返回：当前状态与目标之间的差异输出

5. git_commit

   • 将更改记录到仓库中
   • 输入：
     • repo_path（string）：Git 仓库路径
     • message（string）：提交说明
   • 返回：包含新提交哈希的确认信息；如果没有暂存任何内容，则返回错误（与不带 --allow-empty 的 git commit 一致）；但在合并进行中时（存在 MERGE_HEAD），Git 也允许空提交。合并进行中时，此提交会结束合并：其父提交为 HEAD 和每个 MERGE_HEAD 提交，并清除合并状态

6. git_add

   • 将文件内容添加到暂存区
   • 输入：
     • repo_path（string）：Git 仓库路径
     • files（string[]）：非空文件路径数组，用于暂存；["."] 会暂存所有内容
   • 返回：已暂存文件的确认信息；如果调用未更改索引，则返回未暂存任何内容的提示

7. git_reset

   • 取消暂存所有已暂存的更改
   • 输入：
     • repo_path（string）：Git 仓库路径
   • 返回：重置操作的确认信息

8. git_log

   • 显示提交日志，可按日期筛选
   • 输入：
     • repo_path（string）：Git 仓库路径
     • max_count（number，可选）：要显示的最大提交数（默认值：10）
     • start_timestamp（string，可选）：筛选提交的起始时间戳。接受 ISO 8601 格式（例如，'2024-01-15T14:30:25'）、相对日期（例如，'2 weeks ago'、'yesterday'）或绝对日期（例如，'2024-01-15'、'Jan 15 2024'）
     • end_timestamp（string，可选）：筛选提交的结束时间戳。接受 ISO 8601 格式（例如，'2024-01-15T14:30:25'）、相对日期（例如，'2 weeks ago'、'yesterday'）或绝对日期（例如，'2024-01-15'、'Jan 15 2024'）
   • 返回：包含哈希、作者、日期和说明的提交条目数组

9. git_create_branch

   • 创建新分支
   • 输入：
     • repo_path（字符串）：Git 仓库路径
     • branch_name（字符串）：新分支的名称
     • base_branch（字符串，可选）：要从其创建分支的基分支（默认为当前分支）
   • 返回：分支创建确认

10. git_checkout

• 切换分支
• 输入：
  • repo_path（字符串）：Git 仓库路径
  • branch_name（字符串）：要切换到的分支名称
• 返回：分支切换确认；如果 branch_name 不是分支（而是 sha、标签或其他修订版本），则返回 HEAD is now detached at <short sha>

11. git_show

• 显示提交内容，或指定修订版本中的文件或目录
• 输入：
  • repo_path（字符串）：Git 仓库路径
  • revision（字符串）：要显示的修订版本（提交哈希、分支名称、标签）或对象规格（HEAD:path/to/file）
• 返回：指定的提交内容、文件内容或目录列表

12. git_branch

• 列出 Git 分支
• 输入：
  • repo_path（字符串）：Git 仓库路径。
  • branch_type（字符串）：要列出的分支类型：本地分支（'local'）、远程分支（'remote'）或所有分支（'all'）。
  • contains（字符串，可选）：分支应包含的提交 sha。如果未指定提交 sha，请勿为此参数传入任何内容
  • not_contains（字符串，可选）：分支不应包含的提交 sha。如果未指定提交 sha，请勿为此参数传入任何内容
• 返回：分支列表

协议版本

该服务通过 stdio 同时支持 Model Context Protocol 的两个时期，无需进行任何配置：2026-07-28 客户端（通过 server/discover 发现，无会话）和 2025-11-25 客户端（通过 initialize 握手）。客户端的首个请求决定使用哪个版本。两种版本中的工具行为相同。

Roots 在 2026-07-28 版本中已弃用，并且此服务在任一时期都不会向客户端请求 Roots：仓库访问仅由 --repository 提供；如果未指定 --repository，则由每次工具调用的 repo_path 提供。对于 2026-07-28 规范移除的方法（例如 ping），仅在 2025-11-25 连接上响应。

错误

• 工具执行失败时，会返回 isError: true 的结果，其文本为 Error executing tool <name>: <message>，以便模型读取错误并修正调用。此情况包括 Git 错误（未知修订版本、命令执行失败）、不是仓库或位于 --repository 范围之外的 repo_path、标志注入防护，以及与工具输入架构不匹配的参数。
• 工具名称未知时，会产生协议错误 JSON-RPC -32602（Unknown tool: <name>），这符合两个时期的规范。2.0.0 之前的版本会返回 isError 结果。

安装

使用 uv（推荐）

使用 uv 时无需特定安装。我们将使用 uvx 直接运行 mcp-server-git。

使用 PIP

或者，你也可以通过 pip 安装 mcp-server-git：

pip install mcp-server-git

安装后，可以将其作为脚本运行：

python -m mcp_server_git

配置

--repository（-r）接受 Git 工作树内的任意路径。服务启动时会向上查找其所属的仓库根目录，方式与 git rev-parse --show-toplevel 相同，因此，从仓库的任意子目录启动共享配置时，--repository . 都能正常工作。因此，指定仓库内的路径后，可以在该仓库中的任意位置调用工具，而不仅限于所给的子目录。路径不存在或不在 Git 仓库内时，启动时会记录一行错误。

在 Claude Desktop 中使用

将以下内容添加到 claude_desktop_config.json：

"mcpServers": {
  "git": {
    "command": "uvx",
    "args": ["mcp-server-git", "--repository", "path/to/git/repo"]
  }
}

"mcpServers": {
  "git": {
    "command": "docker",
    "args": ["run", "--rm", "-i", "--mount", "type=bind,src=/Users/username,dst=/Users/username", "mcp/git"]
  }
}

"mcpServers": {
  "git": {
    "command": "python",
    "args": ["-m", "mcp_server_git", "--repository", "path/to/git/repo"]
  }
}

在 VS Code 中使用

如需快速安装，请使用下方的一键安装按钮之一……

如需手动安装，可以使用以下任一方法配置 MCP 服务：

方法 1：用户配置（推荐） 将配置添加到用户级 MCP 配置文件。打开命令面板（Ctrl + Shift + P），并运行 MCP: Open User Configuration。这将打开你的用户 mcp.json 文件，你可以在其中添加服务配置。

方法 2：工作区配置 或者，你也可以在工作区中的 .vscode/mcp.json 文件内添加配置。这样便可以与他人共享此配置。

如需了解 VS Code 中 MCP 配置的更多详情，请参阅 VS Code 官方 MCP 文档。

{
  "servers": {
    "git": {
      "command": "uvx",
      "args": ["mcp-server-git"]
    }
  }
}

Docker 安装：

{
  "mcp": {
    "servers": {
      "git": {
        "command": "docker",
        "args": [
          "run",
          "--rm",
          "-i",
          "--mount", "type=bind,src=${workspaceFolder},dst=/workspace",
          "mcp/git"
        ]
      }
    }
  }
}

在 Zed 中使用

将以下内容添加到 Zed 的 settings.json：

"context_servers": [
  "mcp-server-git": {
    "command": {
      "path": "uvx",
      "args": ["mcp-server-git"]
    }
  }
],

"context_servers": {
  "mcp-server-git": {
    "command": {
      "path": "python",
      "args": ["-m", "mcp_server_git"]
    }
  }
},

在 Zencoder 中使用

1. 前往 Zencoder 菜单（……）
2. 从下拉菜单中选择 Agent Tools
3. 点击 Add Custom MCP
4. 添加名称（即 git）和下方的服务配置，并确保点击 Install 按钮

{
    "command": "uvx",
    "args": ["mcp-server-git", "--repository", "path/to/git/repo"]
}

调试

你可以使用 MCP 检查器调试服务。对于 uvx 安装：

npx @modelcontextprotocol/inspector uvx mcp-server-git

如果你已将软件包安装到特定目录，或正在进行开发：

cd path/to/servers/src/git
npx @modelcontextprotocol/inspector uv run mcp-server-git

运行 tail -n 20 -f ~/Library/Logs/Claude/mcp*.log 将显示服务日志，或许能帮助你调试问题。

开发

测试与覆盖率

测试套件通过 MCP ClientSession 在进程内驱动 serve()（参见 tests/conftest.py），而 tests/test_eras.py 会分别以 2026-07-28 和 2025-11-25 客户端的身份运行 Client。在 src/git 目录中运行：

uv run --frozen pytest                 # the tests
uv run --frozen pytest --cov --cov-report=term-missing --cov-report=json

第二条命令会对 src/mcp_server_git 进行分支覆盖率统计，按文件打印结果，并写入 coverage.json（已被 git 忽略）。每个文件的行覆盖率和分支覆盖率都必须保持在 90% 或以上。无法执行到的代码应标记为 # pragma: no cover # <reason>，而不是降低这一标准。

在客户端中试用更改

有两种方法可以在客户端中试用更改：

1. 运行 MCP 检查器来测试更改。运行说明请参见调试。

2. 使用 Claude 桌面应用进行测试。在 claude_desktop_config.json 中添加以下内容：

Docker

{
  "mcpServers": {
    "git": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--mount", "type=bind,src=/Users/username/Desktop,dst=/projects/Desktop",
        "--mount", "type=bind,src=/path/to/other/allowed/dir,dst=/projects/other/allowed/dir,ro",
        "--mount", "type=bind,src=/path/to/file.txt,dst=/projects/path/to/file.txt",
        "mcp/git"
      ]
    }
  }
}

UVX

{
"mcpServers": {
  "git": {
    "command": "uv",
    "args": [
      "--directory",
      "/<path to mcp-servers>/mcp-servers/src/git",
      "run",
      "mcp-server-git"
    ]
    }
  }
}

构建

Docker 构建：

cd src/git
docker build -t mcp/git .

许可证

此 MCP 服务采用 MIT 许可证。这意味着您可以自由使用、修改和分发该软件，但须遵守 MIT 许可证的条款和条件。详情请参阅项目仓库中的 LICENSE 文件。