内容
# git-mcp
[](https://github.com/selfagency/git-mcp/actions/workflows/ci.yml) [](https://codecov.io/gh/selfagency/git-mcp) 
> 一个 Git [MCP](https://modelcontextprotocol.io) 服务器，不会让人失望
向任何与 MCP 兼容的 AI 代理公开整个 Git 工作流程 - 检查、编写、分支、远程、储藏、变基、LFS、git-flow、文档查找等。默认情况下设计为安全、可组合且快速。由 [`simple-git`](https://github.com/steveukx/git-js) 提供支持。
为 GitHub Copilot、Claude Code、Cursor 和 OpenAI Codex 等工具中的编码代理而构建，同时与任何可以调用工具和资源的 MCP 客户端保持兼容。
---
## 功能
- **11 个分组工具，60+ 个操作**，涵盖日常 Git 工作流程和高级恢复操作
- **安全性第一** - 破坏性操作需要显式确认；强制推送和钩子绕过需经服务器配置允许
- **GPG/SSH 签名**，用于提交和标签，支持服务器级自动签名
- **Git LFS** - 跟踪模式、管理对象、安装钩子、迁移历史
- **Git Flow** - git-flow-next 风格的工作流程支持，带有预设初始化、概览、配置 CRUD、通用主题操作、完成恢复、可选钩子/过滤器对齐和经典功能/发布/热修复/支持别名，无需外部 CLI
- **文档查找** - 搜索 git-scm.com 并直接从 LLM 获取手册页
- **MCP 资源** - 状态、日志、分支和差异的 URI 可寻址只读视图
- **捆绑代理技能** - `skills/git-mcp-workflow/` 记录了 MCP-first Git 工作流程、恢复、工作树、发布和高级操作，适用于 AI 代理和编码代理；可通过 [`skills-npm`](https://github.com/antfu/skills-npm) 和 [skill.sh](https://skills.sh/) 安装
- **多仓库** - 传递 `repo_path` 每次调用或配置服务器级默认值
- **跨平台** - macOS、Linux、Windows（Git for Windows）
---
## 快速开始
### npx（无需安装）
```bash
npx @selfagency/git-mcp --repo-path /path/to/your/repo
```
### 全局安装
```bash
npm install -g @selfagency/git-mcp
git-mcp --repo-path /path/to/your/repo
```
### Claude 桌面版
将以下内容添加到 `~/Library/Application Support/Claude/claude_desktop_config.json`：
```json
{
"mcpServers": {
"git": {
"command": "npx",
"args": ["-y", "@selfagency/git-mcp", "--repo-path", "/path/to/your/repo"]
}
}
}
```
### VS Code（Copilot）
将以下内容添加到项目中的 `.vscode/mcp.json`：
```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` |
---
## 工具参考
工具按领域分组。每个根工具都有一个 `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` | 完整的 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，带有可配置模式（软/混合/硬） |
| `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` | 二分查找回归（启动、良好、坏、重置、日志） |
| `tag` | 创建、列出、删除或推送标签；支持 GPG/SSH 签名 |
| `worktree` | 添加、列出、删除或修剪链接的工作树 |
| `submodule` | 添加、更新、同步、初始化、取消初始化和列出子模块 |
### Git Flow（`git_flow`）
预设 git-flow-next 工作流程，无需外部 CLI。
| 操作 | 描述 |
| --- | --- |
| `init` | 使用 git-flow 分支约定初始化仓库 |
| `overview` | 显示当前流程状态和活动分支 |
| `config` | 读取或写入 git-flow 配置值 |
| `topic` | 通用主题分支操作（启动、完成、发布、跟踪） |
| `control` | 流程控制：恢复中断的完成、取消或恢复 |
### 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_ping`）
返回服务器状态。用于确认服务器是否可达。
---
## MCP 资源
URI 可寻址只读快照（支持订阅）：
| 资源 URI | 内容 |
| --- | --- |
| `git+repo://status/{repo_path}` | 工作树状态（JSON） |
| `git+repo://log/{repo_path}` | 最近的提交日志（JSON） |
| `git+repo://branches/{repo_path}` | 分支列表（JSON） |
| `git+repo://diff/{repo_path}` | 未暂存 + 暂存差异（JSON） |
---
## 捆绑代理技能
git-mcp 附带一个捆绑代理技能 `skills/git-mcp-workflow/`，该技能教导任何 `skills-npm` 兼容的代理如何使用 MCP 工具界面而不是运行原始 `git` CLI 命令。该技能涵盖：
- 为什么 LLM 不能使用 Git CLI（引用危险、静默失败）
- 检查-变异工作流程规则
- 撤销和恢复操作的 安全顺序
- 完整的注册工具界面与操作参考
- 工作流程手册：功能分支、变基、恢复、工作树、回移植、发布标签、Git Flow、合并
- Git 概念解释锚定到 MCP 工具
### 安装技能
如果您的代理支持 [skills-npm](https://github.com/antfu/skills-npm)：
```bash
npm install @selfagency/git-mcp # 或 pnpm/yarn
npx skills-npm
```
或添加到您的项目的 `package.json` 中，以便它自动运行：
```json
{
"scripts": {
"prepare": "skills-npm"
}
}
```
然后添加到 `.gitignore`：
```txt
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` 钩子和过滤器执行被禁用
- 路径针对仓库根目录进行验证 - 拒绝遍历尝试
- 凭证和令牌从不包含在响应中
---
## 开发
```bash
# 克隆并安装
git clone https://github.com/selfagency/git-mcp.git
cd git-mcp
pnpm install
# 在开发模式下运行（热重载）
pnpm dev
# 构建
pnpm build
# 运行测试
pnpm test
# 类型检查
pnpm typecheck
# 整理
pnpm lint
# 文档（开发服务器）
pnpm docs:dev
# 文档（构建）
pnpm docs:build
```
---
## 许可证
MIT © [Daniel Sieradski](https://self.agency)
