MCP 服务器

git-mcp-server

Local Git MCP server exposing 29 tools that let AI clients manage repositories, commits, branches, remotes, and advanced git operations via natural language.

README

git-mcp-server

本地 Git MCP 服务器：将 git 操作封装为 29 个 MCP 工具，供 AI 客户端直接调用。让 AI 像人一样读写仓库——查看状态、暂存提交、查询历史、管理分支与远程，全程无需离开对话。

快速开始

前置条件

Python ≥3.13
uv
系统已安装 git

方式一：配置到 opencode（`opencode.json`）

{
  "mcp": {
    "git": {
      "type": "local",
      "command": ["uvx", "--from", "git+https://github.com/JessPig/git-mcp-server", "git-mcp-server"],
      "enabled": true
    }
  }
}

方式二：在对话中让 opencode 自动安装

添加 git MCP 服务器，用 uvx --from git+https://github.com/JessPig/git-mcp-server git-mcp-server 启动

安装后即可在对话中说「查看仓库状态」「提交所有更改」「创建新分支」——AI 会直接调用对应工具完成。

配置

环境变量	说明
`GIT_MCP_ALLOWED_DIRS`	`os.pathsep` 分隔的允许目录列表（如 `/home/user/repos;/home/user/projects`）。未设置时默认限制在服务器启动目录（隐式沙箱）。
`GIT_MCP_ALLOW_FORCE_PUSH`	是否允许强制推送（默认 false 禁用，设为 true 启用；启用后 force 仍需 confirmed）

工具一览

共 29 个工具，分 6 大分组：

仓库管理

工具	说明
`git_init`	初始化仓库（可指定初始分支、裸仓库）
`git_clone`	克隆远程仓库到本地（支持浅克隆、指定分支）
`git_status`	查看工作区状态（可隐藏未跟踪文件）
`git_clean`	删除/预览未跟踪文件（需确认）
`git_config`	读取 git 配置（指定 key 或全量列出）

暂存与提交

工具	说明
`git_add`	暂存文件（全量/更新/指定文件）
`git_commit`	创建提交（支持 amend、no-verify）
`git_diff`	查看差异（工作区/暂存区/提交间对比，支持 stat）

历史查询

工具	说明
`git_log`	查看提交历史（支持作者/日期/消息过滤）
`git_show`	查看提交的元数据与补丁
`git_blame`	逐行追溯文件修改归属（可限定行范围）
`git_reflog`	查看引用日志
`git_grep`	在跟踪文件中搜索模式

分支操作

工具	说明
`git_branch`	列出/创建/删除分支（delete 需确认）
`git_checkout`	切换分支、标签或提交（可先创建新分支）
`git_merge`	合并分支到当前分支（冲突返回详情）
`git_rebase`	变基或管理进行中的 rebase
`git_cherry_pick`	将指定提交应用到当前分支

远程操作

工具	说明
`git_remote`	管理远程仓库（list/add/remove/rename）
`git_fetch`	从远程拉取引用
`git_pull`	拉取并合并（支持 rebase）
`git_push`	推送到远程（force/tags，拒绝时返回详情）

高级操作

工具	说明
`git_tag`	列出/创建/删除标签（annotated 标签需 message）
`git_stash`	管理stash（list/push/pop/drop）
`git_reset`	重置到指定提交（soft/mixed/hard，需确认）
`git_revert`	反向提交（不改变历史）
`git_worktree`	管理并行工作树（list/add/remove）
`git_bisect`	二分查找引入 bug 的提交
`git_submodule`	管理子模块（status/add/update）

核心特性

完整的 git 工作流覆盖：从 init/clone 到 bisect/submodule，29 个工具涵盖日常开发全场景
官方 MCP SDK：基于 mcp 包标准 stdio 传输，兼容任意支持 MCP 的客户端；工具契约由 Pydantic schema 定义
可自纠的错误反馈：失败时返回 is_error 结果及具体信息，调用方 LLM 可据此自行修正
只读/破坏性标注：工具标注 readOnlyHint / destructiveHint，客户端可据此给予不同级别的安全提示
四层安全防线：路径白名单、防 flag 注入、ref 预校验、破坏性操作显式确认（详见下方）

安全模型

防线	机制
路径白名单	仓库路径经 `resolve()` + `relative_to()` 校验，限定在 `GIT_MCP_ALLOWED_DIRS` 内，防 `../` 逃逸
防 flag 注入	ref / branch / target 等参数拒绝以 `-` 开头
ref 预校验	`rev_parse` 预先确认 ref 真实存在
破坏性确认	`git_reset`、`git_clean`、`git_branch delete` 等 12 个工具要求显式 `confirmed=True`；`git_reset`/`git_checkout`（force）支持 preview 先行查看将丢弃的变更

只读 vs 破坏性工具分类

只读（8 个）：git_status git_diff git_log git_show git_blame git_reflog git_grep git_config
破坏性（12 个）：git_reset git_clean git_revert git_merge git_rebase git_cherry_pick git_push git_branch git_checkout git_stash git_tag git_worktree

工作原理

AI 客户端 (opencode / Claude Desktop / ...)
    │
    │  stdio (MCP 协议)
    ▼
git-mcp-server
    │
    ├─ list_tools → 29 个工具名 + Pydantic schema + 只读/破坏性标注
    │
    └─ call_tool → 路径边界校验 → ref/确认校验 → GitPython 执行 → 文本返回

服务器启动时读取 GIT_MCP_ALLOWED_DIRS，随后通过 stdio 与客户端通信。所有 git 操作经 GitPython 执行，按 6 个模块组织（tools_repo / tools_stage / tools_history / tools_branch / tools_remote / tools_advanced）。