Git MCP Server (Rust)

一个高性能的 Rust 版 Git MCP Server，为 AI 代理提供完整的 Git 操作能力。

特性

28 个 Git 工具 - 覆盖所有常用 Git 操作 + changelog 分析 + wrap-up 指令
STDIO / HTTP 传输 - 支持 STDIO 与 streamable-http 风格单端点
会话工作目录 - 支持动态切换项目目录
MCP Resources / Prompts - 支持 resources/list|read 与 prompts/list|get
安全路径验证 - 可配置的基础目录限制
高性能 - Rust 实现，单二进制部署

安装

方式一：从源码构建

# 克隆仓库
git clone https://github.com/QiuZH001/git-mcp-server-rust.git
cd git-mcp-server-rust

# 构建 release 版本
cargo build --release

# 二进制文件位置
./target/release/git-mcp-server

方式二：直接下载

# 下载预编译二进制（如果可用）
# 或复制已编译的二进制到任意位置
cp ./target/release/git-mcp-server /usr/local/bin/

前置要求

Rust 1.70+（仅从源码构建时需要）
Git 2.0+
系统：macOS / Linux / Windows

配置

环境变量

| 变量 | 描述 | 默认值 | 示例 | |------|------|--------|------| | GIT_BASE_DIR | 限制操作的基础目录 | 无（任意目录） | /Users/you/projects | | GIT_USERNAME | Git 提交者名称 | 全局 git config | John Doe | | GIT_EMAIL | Git 提交者邮箱 | 全局 git config | john@example.com | | GIT_SIGN_COMMITS | 启用提交签名 | false | true | | GIT_WRAPUP_INSTRUCTIONS_PATH | 自定义 wrap-up 指令文件路径 | 无 | /path/to/wrapup.md | | MCP_LOG_LEVEL | 日志级别 | info | debug, warn, error | | MCP_TRANSPORT_TYPE | 传输类型 | stdio | http | | MCP_HTTP_HOST | HTTP 监听地址 | 127.0.0.1 | 127.0.0.1 | | MCP_HTTP_PORT | HTTP 监听端口 | 3015 | 3015 | | MCP_HTTP_ENDPOINT_PATH | HTTP MCP 端点路径 | /mcp | /mcp | | MCP_AUTH_MODE | HTTP 认证模式 | none | none, jwt, oauth | | MCP_AUTH_SECRET_KEY | JWT(HS256) 密钥（jwt 模式） | 无 | your-secret | | OAUTH_ISSUER_URL | OAuth issuer（oauth 模式） | 无 | https://issuer.example | | OAUTH_AUDIENCE | OAuth audience（oauth 模式） | 无 | git-mcp-server | | OAUTH_PUBLIC_KEY_PEM | OAuth RS256 公钥 PEM（oauth 模式） | 无 | -----BEGIN PUBLIC KEY-----... | | MCP_ALLOWED_ORIGINS | 允许的 Origin 白名单（逗号分隔） | 无 | https://a.com,https://b.com | | MCP_SESSION_MODE | HTTP 会话模式 | auto | stateless, stateful | | MCP_RESPONSE_FORMAT | tools/call 文本输出格式 | json | json, markdown, auto | | MCP_RESPONSE_VERBOSITY | tools/call 输出详略 | standard | minimal, standard, full |

MCP 客户端配置

Claude Code

编辑 ~/.claude/claude_desktop_config.json：

{
  "mcpServers": {
    "git": {
      "command": "/path/to/git-mcp-server",
      "env": {
        "GIT_BASE_DIR": "/Users/yourname/projects",
        "GIT_USERNAME": "Your Name",
        "GIT_EMAIL": "your@email.com"
      }
    }
  }
}

Cursor

编辑 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "git": {
      "command": "/path/to/git-mcp-server",
      "env": {
        "GIT_BASE_DIR": "/Users/yourname/projects"
      }
    }
  }
}

Windsurf

编辑 Windsurf 配置文件：

{
  "mcpServers": {
    "git": {
      "command": "/path/to/git-mcp-server",
      "args": [],
      "env": {
        "GIT_BASE_DIR": "/home/user/code"
      }
    }
  }
}

OpenCode

编辑 opencode MCP 配置：

{
  "mcpServers": {
    "git": {
      "command": "/path/to/git-mcp-server",
      "env": {
        "GIT_BASE_DIR": "/path/to/your/projects",
        "MCP_LOG_LEVEL": "debug"
      }
    }
  }
}

工具列表

仓库管理

| 工具 | 描述 | 关键参数 | |------|------|----------| | git_init | 初始化新仓库 | path, initial_branch, bare | | git_clone | 克隆远程仓库 | url, local_path, branch, depth | | git_status | 查看工作区状态 | path, include_untracked | | git_clean | 删除未跟踪文件 | force, dry_run, directories |

暂存与提交

| 工具 | 描述 | 关键参数 | |------|------|----------| | git_add | 暂存文件 | files, all, update, force | | git_commit | 创建提交 | message, amend, files_to_stage, no_verify | | git_diff | 查看差异 | target, source, staged, stat |

历史查询

| 工具 | 描述 | 关键参数 | |------|------|----------| | git_log | 查看提交历史 | max_count, author, since, until, grep | | git_show | 显示对象详情 | object, format, stat | | git_blame | 逐行追溯 | file, start_line, end_line | | git_reflog | 引用日志 | ref, max_count |

分支操作

| 工具 | 描述 | 关键参数 | |------|------|----------| | git_branch | 分支管理 | operation, name, force, all | | git_checkout | 切换分支/恢复 | target, create_branch, force | | git_merge | 合并分支 | branch, no_fast_forward, squash | | git_rebase | 变基操作 | upstream, mode, interactive | | git_cherry_pick | 摘取提交 | commits, no_commit |

远程操作

| 工具 | 描述 | 关键参数 | |------|------|----------| | git_remote | 远程仓库管理 | mode, name, url | | git_fetch | 获取远程更新 | remote, prune, tags | | git_pull | 拉取并合并 | remote, branch, rebase | | git_push | 推送到远程 | remote, branch, force, tags |

高级操作

| 工具 | 描述 | 关键参数 | |------|------|----------| | git_tag | 标签管理 | mode, tag_name, message, annotated | | git_stash | 暂存区管理 | mode, message, stash_ref | | git_reset | 重置 HEAD | mode, target, confirmed | | git_worktree | 工作树管理 | mode, worktree_path, branch | | git_set_working_dir | 设置会话目录 | path | | git_clear_working_dir | 清除会话目录 | confirm | | git_changelog_analyze | 提供 changelog 分析上下文与指令 | path, reviewTypes, maxCommits, sinceTag, branch | | git_wrapup_instructions | 返回收尾流程指令与当前状态 | acknowledgement, updateAgentMetaFiles, createTag |

MCP 方法

支持以下 MCP / JSON-RPC 方法：

initialize
tools/list
tools/call
resources/list
resources/read
prompts/list
prompts/get

Resources

git://working-directory：返回当前会话工作目录

Prompts

git_wrapup：Git 收尾工作流提示词模板（支持参数）

使用示例

示例 1：初始化并提交

AI: 帮我在 /projects/my-app 初始化一个 git 仓库并做第一次提交

1. 使用 git_init 初始化仓库
2. 使用 git_add 添加所有文件
3. 使用 git_commit 创建初始提交

示例 2：查看项目状态

AI: 查看当前项目的 git 状态

使用 git_status 查看分支、暂存文件、未跟踪文件等

示例 3：创建功能分支

AI: 创建一个名为 feature/login 的分支并切换过去

1. git_branch 创建分支
2. git_checkout 切换分支

示例 4：查看提交历史

AI: 查看最近 10 条提交记录

使用 git_log 并设置 max_count=10

示例 5：推送代码

AI: 将当前分支推送到 origin

使用 git_push，设置 remote=origin, branch=当前分支

工作目录管理

设置工作目录

在执行任何 Git 操作前，建议先设置工作目录：

使用 git_set_working_dir 设置项目路径
参数: { "path": "/path/to/your/project" }

清除工作目录

使用 git_clear_working_dir 清除会话中的工作目录设置
参数: { "confirm": "Y" }

安全特性

路径限制

设置 GIT_BASE_DIR 后，所有操作将被限制在该目录及其子目录内：

{
  "env": {
    "GIT_BASE_DIR": "/Users/you/safe-projects"
  }
}

尝试访问 GIT_BASE_DIR 外的路径将返回错误。

危险操作确认

以下操作需要明确确认：

git_reset (hard 模式) - 需要 confirmed: true
git_clean - 需要 force: true
git_push --force - 需要 force: true

故障排除

常见问题

Q: 服务器启动后无响应

确保使用 STDIO 传输模式，检查日志输出：

MCP_LOG_LEVEL=debug ./git-mcp-server

Q: Git 操作失败 "command not found"

确保系统已安装 Git 并在 PATH 中：

which git

Q: 权限被拒绝

检查 GIT_BASE_DIR 配置和文件系统权限。

Q: 中文文件名乱码

确保系统 locale 设置正确：

export LANG=en_US.UTF-8

调试模式

启用详细日志：

{
  "env": {
    "MCP_LOG_LEVEL": "debug"
  }
}

开发

运行测试

# 运行所有测试
cargo test

# 运行单个测试
cargo test test_git_status

# 带输出运行
cargo test -- --nocapture

代码检查

cargo clippy
cargo fmt -- --check

与 TypeScript 版本对比

| 特性 | Rust 版本 | TypeScript 版本 | |------|----------|-----------------| | 性能 | 更快（编译型） | 较慢（解释型） | | 部署 | 单二进制 | 需要 Node.js | | 内存 | 更低 | 较高 | | 启动时间 | 毫秒级 | 秒级 | | 依赖 | 无运行时依赖 | npm 依赖 |

许可证

Apache-2.0