Git MCP

git-mcp

一个好用的 Git MCP 服务

向任何兼容 MCP 的 AI Agent 提供完整的 Git 工作流——检查、写入、分支、远程仓库、暂存、变基、LFS、git-flow、文档查询等。默认安全、可组合且快速。由 simple-git 驱动。

专为 GitHub Copilot、Claude Code、Cursor 和 OpenAI Codex 等工具中的编码 Agent 打造，同时兼容任何能够调用工具和资源的 MCP 客户端。

---

功能

• 18 个工具，包含 80 多项操作，涵盖日常 Git 工作流、高级恢复、历史重写、仓库分析、代码托管平台拉取请求以及对外部版本控制系统的识别
• 安全优先——破坏性操作需要明确确认；强制推送和绕过钩子需在服务器配置中显式启用
• 支持提交和标签的 GPG/SSH 签名，并支持服务器级自动签名
• Git LFS——跟踪模式、管理对象、安装钩子、迁移历史
• Git Flow——驱动 git-flow-next CLI，确保随着 CLI 的演进，完成状态机、冲突恢复和工作树生命周期依然正确。支持预设初始化、概览、配置增删改查、通用主题操作，以及经典的 feature/release/hotfix/support 别名
• 文档查询——搜索 git-scm.com，并直接从大模型获取 man 手册页
• MCP 资源——可通过 URI 访问状态、日志、分支和差异的只读视图
• 内置 Agent 技能——skills/git-mcp-workflow/ 为 AI Agent 和编码 Agent 介绍 MCP 优先的 Git 工作流、恢复、工作树、发布及高级操作；可通过 skills-npm 和 skill.sh 安装
• 识别外部版本控制系统——git_but_check / git_jj_check 可检测 GitButler 和 Jujutsu，并在适当时引导 Agent 优先使用它们的原生 CLI/MCP（并提供 but teardown 指引），而非 git-mcp 工具
• 历史重写——git_rewrite：用于安全重写提交历史的重述、压缩、重写消息和备份/恢复功能
• 仓库分析——git_analytics：根据本地 Git 历史计算贡献者、代码变动量、活动、摘要和文件统计信息
• 拉取请求——git_pr：通过提供商 CLI 或 REST API，在 GitHub、GitLab、Forgejo、Gitea 和 Bitbucket 上创建、列出和合并 PR/MR
• Tangled 与 Entire 识别——git_tangled_check / git_entire_check 可检测 Tangled 托管服务以及 Entire 会话/上下文管理
• 多仓库——可在每次调用时传入 repo_path，或配置服务器级默认值
• 工作树——git_worktree：可按路径使用普通的 git worktree，或通过 git flow worktree 使用按分支寻址的工作树，支持路径模板和感知来源的清理
• 跨平台——macOS、Linux、Windows（Git for Windows）均由 CI 覆盖

---

快速开始

npx（无需安装）

npx @selfagency/git-mcp --repo-path /path/to/your/repo

全局安装

npm install -g @selfagency/git-mcp
git-mcp --repo-path /path/to/your/repo

Claude Desktop

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "git": {
      "command": "npx",
      "args": ["-y", "@selfagency/git-mcp", "--repo-path", "/path/to/your/repo"]
    }
  }
}

VS Code（Copilot）

添加到项目中的 .vscode/mcp.json：

{
  "servers": {
    "git": {
      "command": "npx",
      "args": ["-y", "@selfagency/git-mcp", "--repo-path", "${workspaceFolder}"]
    }
  }
}

---

配置

所有配置均通过环境变量进行。请在 MCP 客户端配置中传入这些变量：

变量	默认值	描述
GIT_REPO_PATH	—	默认仓库路径（也可使用 --repo-path CLI 参数）
GIT_ALLOW_NO_VERIFY	false	允许在提交/推送时使用 --no-verify（绕过钩子）
GIT_ALLOW_FORCE_PUSH	false	允许推送时使用 --force
GIT_ALLOW_FLOW_HOOKS	false	允许执行 git_flow 钩子和筛选器
GIT_AUTO_SIGN_COMMITS	false	自动签署每次提交
GIT_AUTO_SIGN_TAGS	false	自动签署每个标签
GIT_SIGNING_KEY	—	默认 GPG 密钥 ID 或 SSH 密钥路径
GIT_SIGNING_FORMAT	—	签署格式：openpgp、ssh 或 x509
GIT_ALLOW_BUT	false	启用 GitButler 感知（git_but_check）
GIT_ALLOW_JJ	false	启用 Jujutsu 感知（git_jj_check）
GIT_ALLOW_TANGLED	false	启用 Tangled 感知（git_tangled_check）
GIT_ALLOW_ENTIRE	false	启用 Entire 感知（git_entire_check）
BUT_BINARY	but	覆盖 but 可执行文件路径
JJ_BINARY	jj	覆盖 jj 可执行文件路径
ENTIRE_BINARY	entire	覆盖 entire 可执行文件路径
GITHUB_TOKEN	—	git_pr REST 回退所用的 GitHub 令牌
GITLAB_TOKEN	—	git_pr REST 回退所用的 GitLab 令牌
FORGEJO_TOKEN	—	git_pr REST 回退所用的 Forgejo/Gitea 令牌
BITBUCKET_TOKEN	—	git_pr REST 回退所用的 Bitbucket 令牌
GIT_FORGE_PROVIDER	—	为可自托管实例指定的 Forge 提供商

---

工具参考

工具按领域分组。每个根工具都接受一个 action 参数，用于选择操作。标记为默认的操作在省略 action 时会被使用。

上下文（git_context）

操作	描述
summary	(默认) 仓库完整快照：分支、上游、待处理更改和正在进行的操作
search	搜索提交历史和工作树内容
get_config	读取 Git 配置值
set_config	写入 Git 配置值
aliases	列出所有已配置的 Git 别名

状态（git_status）

操作	描述
status	(默认) 工作树和分支状态
diff	未暂存、已暂存或引用之间的差异
diff_main	分支相对 main（或可配置的基准分支）的分叉点以来的更改

历史记录（git_history）

操作	描述
log	（默认） 提交日志，支持筛选、分页、修订范围和路径规格
show	查看单个提交
blame	逐行显示文件的归属信息
reflog	完整的引用日志——恢复记录
lg	紧凑的图形日志（--oneline --graph --decorate --all）
who	贡献者简要日志（支持可选的 file_path）

提交（git_commits）

操作	描述
add	暂存文件或代码块
restore	丢弃工作区更改
unstage	从暂存区移除文件
commit	创建提交，支持消息、签名和作者标志
amend	修改上一次提交，但不编辑提交消息
wip	暂存所有更改，并以消息 WIP 创建提交
revert	为指定引用创建还原提交
undo	软重置上一次提交（reset --soft HEAD~1）
reset	重置 HEAD，可配置模式（soft/mixed/hard）
nuke	硬重置上一次提交——需要 confirm=true

分支（git_branches）

操作	描述
list	（默认） 列出本地和远程分支
create	创建分支
delete	删除分支
rename	重命名分支
checkout	切换到分支或引用
set_upstream	设置或更新跟踪上游
recent	按提交者日期排序的近期分支

远程仓库（git_remotes）

操作	描述
list	（默认） 列出已配置的远程仓库
manage	添加、移除或重命名远程仓库
fetch	从远程仓库获取
pull	拉取（获取 + 合并/变基）
push	推送到远程仓库；支持 force_with_lease

工作区（git_workspace）

操作	描述
stash	暂存并弹出/应用/丢弃/列出/显示储藏条目
stash_all	一次操作中暂存已跟踪和未跟踪的更改
rebase	开始、继续、中止或跳过变基
cherry_pick	应用一个或多个提交；支持继续/中止/跳过
merge	合并分支，支持完整的标志控制
bisect	二分查找回归问题（start、good、bad、reset、log）
tag	创建、列出、删除或推送标签；支持 GPG/SSH 签名
worktree	添加、列出、移除、锁定、解锁、清理或修复关联工作树
submodule	添加、更新、同步、初始化、取消初始化和列出子模块

Git Flow（git_flow）

驱动 git-flow-next CLI，必须先安装并确保在 PATH 中 （brew install git-flow-next，或访问发布页面）。 设置 GIT_FLOW_BINARY 可覆盖路径。如果找不到二进制文件，工具会提示安装方法，而不会含糊地失败。

操作	描述
init	使用 git-flow 分支约定初始化仓库
overview	显示当前工作流状态和活跃分支
config	读取或写入 git-flow 配置值
topic	通用主题分支操作（start、finish、publish、track）
control	恢复或中止正在进行的 finish 或 update

标志的适用范围限定于目标动词：worktree 和 worktree_path 适用于 start 和 checkout， 而 keep_worktree 和 force_worktree 适用于 finish 和 delete。如果不匹配，会引发错误， 而不是被静默丢弃。完整参数列表请参见工具参考。

Worktree（git_worktree）

有两种后端。按路径指定的操作驱动原生 git worktree，只需要 git； 按分支指定的 flow_* 操作驱动 git flow worktree，按分支名称定位工作树， 根据 gitflow.worktreePath 模板计算路径，并标记来源，以便清理时区分由 git-flow 创建的工作树（会被移除） 和手动创建的工作树（会分离，未提交的工作保留）。

操作	描述
add、list、remove、lock、unlock、prune、repair	原生 git worktree，按路径识别
flow_path、flow_add、flow_remove、flow_list	git flow worktree，按分支识别

请参见工具参考。

LFS（git_lfs）

操作	描述
track	将跟踪模式添加到 .gitattributes
untrack	移除跟踪模式
ls-files	列出受 LFS 跟踪的文件
status	显示 LFS 状态
pull	拉取 LFS 对象
push	推送 LFS 对象
install	在仓库中安装 LFS 钩子
migrate-import	将现有历史记录迁移到 LFS
migrate-export	将 LFS 历史记录迁回普通对象

文档（git_docs）

操作	描述
search	搜索 git-scm.com 上的文档
man	获取并返回 Git 手册页

历史重写（git_rewrite）

操作	描述
reword	更改一条提交消息（HEAD 会就地 amend；任意提交通过 filter-branch 修改）
squash	将最近 N 条提交合并为一条（需要 confirm=true）
rewrite-messages	通过 SHA→消息映射表重写某个范围内的消息（需要 confirm=true）
backup	重写前创建 rewrite-backup/<name> 分支
restore	硬重置到备份分支（需要 confirm=true）

分析（git_analytics）

Action	Description
contributors	每位作者的提交数、增减行数、首次／最近活动时间
churn	文件热点（提交最多／变更行数最多的文件）
activity	每日提交频率
summary	分支／标签数量、提交总数、贡献最多者、最早／最新提交
file-stats	文件类型分布、最大文件、最近修改的文件

拉取请求（git_pr）

Action	Description
create	在检测到的托管平台（GitHub、GitLab、Forgejo、Gitea、Bitbucket）上创建 PR/MR
list	列出 PR/MR（按状态筛选）
merge	合并 PR/MR（方式：merge/squash/rebase）

如果本机已安装提供方 CLI（gh/glab/tea），则使用该 CLI；否则使用带有 *_TOKEN 环境变量的 REST API。根据 origin 远程自动检测提供方；可自托管实例使用 GIT_FORGE_PROVIDER。

外部 VCS 感知

Tool	Description
git_but_check	检测 GitButler but CLI；优先使用 but mcp/but，并在 git-mcp 工具前运行 but teardown
git_jj_check	检测 Jujutsu jj CLI 和 .jj/ 管理；对于由 jj 管理的仓库，优先使用 jj CLI
git_tangled_check	检测 Tangled 托管；git 传输可用，PR 通过 Web UI 操作
git_entire_check	检测 Entire CLI 和 .entire/ 管理；使用 entire 查询会话／上下文

健康检查（git_ping）

返回服务状态。可用于确认服务可访问。

---

MCP 资源

可通过 URI 寻址的只读快照（支持订阅）：

Resource URI	Content
git+repo://status/{repo_path}	工作树状态（JSON）
git+repo://log/{repo_path}	最近提交日志（JSON）
git+repo://branches/{repo_path}	分支列表（JSON）
git+repo://diff/{repo_path}	未暂存和已暂存的差异（JSON）

---

捆绑的 Agent 技能

git-mcp 在 skills/git-mcp-workflow/ 中附带一项 Agent 技能，可指导任何兼容 skills-npm 的 Agent 使用 MCP 工具界面，而不是运行原始 git CLI 命令。该技能涵盖：

• LLM 不应使用 Git CLI 的原因（引号处理隐患、静默失败）
• 先检查再修改的工作流规则
• 撤销和恢复操作的安全顺序
• 完整的已注册工具界面及操作参考
• 工作流指南：功能分支、变基、恢复、工作树、回移、发布打标签、Git Flow、合并
• 以 MCP 工具为基础讲解 Git 概念

安装技能

如果你的 Agent 支持 skills-npm：

npm install @selfagency/git-mcp   # or pnpm/yarn
npx skills-npm

或者添加到项目的 package.json，使其自动运行：

{
  "scripts": {
    "prepare": "skills-npm"
  }
}

然后添加到 .gitignore：

skills/npm-*

---

安全

• 所有会修改数据的工具都在其 MCP 注解中设置了 destructiveHint: true
• git_commits action=reset mode=hard 需要设置 confirm=true
• git_commits action=nuke 需要设置 confirm=true
• 除非设置了 GIT_ALLOW_FORCE_PUSH=true，否则禁用强制推送（--force）；force_with_lease 始终可用
• 除非设置了 GIT_ALLOW_NO_VERIFY=true，否则禁用跳过钩子（--no-verify）
• 除非设置了 GIT_ALLOW_FLOW_HOOKS=true，否则禁用 git_flow 钩子和过滤器执行
• 路径会根据仓库根目录进行验证，并拒绝目录遍历尝试
• 响应中绝不会包含凭据和令牌

---

开发

# Clone and install
git clone https://github.com/selfagency/git-mcp.git
cd git-mcp
pnpm install

# Run in development mode (hot reload)
pnpm dev

# Build
pnpm build

# Run tests
pnpm test

# Type check
pnpm typecheck

# Lint
pnpm lint

# Docs (dev server)
pnpm docs:dev

# Docs (build)
pnpm docs:build

---

许可证

MIT © Daniel Sieradski