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）。

许可

MIT