# git-mcp-server

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

## 快速开始

### 前置条件

- [Python ≥3.13](https://www.python.org/downloads/)
- [uv](https://docs.astral.sh/uv/getting-started/installation/)
- 系统已安装 git

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

```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](./LICENSE)