/ 目录 / 演练场 / git-mcp-server
● 社区 cyanheads ⚡ 即开即用

git-mcp-server

作者 cyanheads · cyanheads/git-mcp-server

一个功能齐全的 git MCP — 28 个工具,包括 worktree、stash、reflog、GPG 签名和会话级工作目录,让 Claude 能安全地跨多个仓库操作。

参考 git MCP 涵盖基础功能,而 cyanheads/git-mcp-server 功能更全面。Worktree 管理、可选 commit 签名、路径沙箱、会话隔离的工作目录和响应格式控制(JSON vs Markdown)使其适合多仓库 agent 和企业级工作流。

为什么要用

核心特性

实时演示

实际使用效果

git-2.replay ▶ 就绪
0/0

安装

选择你的客户端

~/Library/Application Support/Claude/claude_desktop_config.json  · Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "git-2": {
      "command": "npx",
      "args": [
        "-y",
        "git-mcp-server"
      ],
      "_inferred": true
    }
  }
}

打开 Claude Desktop → Settings → Developer → Edit Config。保存后重启应用。

~/.cursor/mcp.json · .cursor/mcp.json
{
  "mcpServers": {
    "git-2": {
      "command": "npx",
      "args": [
        "-y",
        "git-mcp-server"
      ],
      "_inferred": true
    }
  }
}

Cursor 使用与 Claude Desktop 相同的 mcpServers 格式。项目级配置优先于全局。

VS Code → Cline → MCP Servers → Edit
{
  "mcpServers": {
    "git-2": {
      "command": "npx",
      "args": [
        "-y",
        "git-mcp-server"
      ],
      "_inferred": true
    }
  }
}

点击 Cline 侧栏中的 MCP Servers 图标,然后选 "Edit Configuration"。

~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "git-2": {
      "command": "npx",
      "args": [
        "-y",
        "git-mcp-server"
      ],
      "_inferred": true
    }
  }
}

格式与 Claude Desktop 相同。重启 Windsurf 生效。

~/.continue/config.json
{
  "mcpServers": [
    {
      "name": "git-2",
      "command": "npx",
      "args": [
        "-y",
        "git-mcp-server"
      ]
    }
  ]
}

Continue 使用服务器对象数组,而非映射。

~/.config/zed/settings.json
{
  "context_servers": {
    "git-2": {
      "command": {
        "path": "npx",
        "args": [
          "-y",
          "git-mcp-server"
        ]
      }
    }
  }
}

加入 context_servers。Zed 保存后热重载。

claude mcp add git-2 -- npx -y git-mcp-server

一行命令搞定。用 claude mcp list 验证,claude mcp remove 卸载。

使用场景

实战用法: git-mcp-server

在单仓库邻近结构的组织中跨 10 个仓库应用相同的重构

👤 平台工程师、开发者关系 ⏱ ~45 min advanced

何时使用: 需要跨多个仓库升级依赖或重命名导入,不想手动克隆和上下文切换

前置条件
  • 本地克隆或写权限 — 已配置 SSH key
步骤
  1. 列举仓库
    列出 ~/code/acme 下的所有仓库。对于每个仓库,切换工作目录,运行 git_status,告诉我当前分支。✓ 已复制
    → 每个仓库的状态
  2. 创建分支并应用改动
    在每个仓库中,创建分支 'chore/bump-foo',在 package.json 中将 foo 从 1.x 升级到 2.x,用 'chore: bump foo' 提交,推送,并开启 PR(via github MCP)。✓ 已复制
    → 每个仓库的 PR URL

结果: 跨仓库改动在一次对话中完成。

注意事项
  • 提交风暴 — 一个不好的重构现在分散在 10 个 PR 中 — 先在一个仓库测试;然后再发送到其余仓库
  • 需要签署 / DCO 但未签署 — 启用 GIT_SIGN_COMMITS 并设置 GIT_USERNAME/GIT_EMAIL
搭配使用: github · filesystem

从两个 tag 之间的 git log 生成发布说明

👤 发布经理 ⏱ ~20 min intermediate

何时使用: 发布版本时想从实际提交而不是记忆中生成更新日志。

步骤
  1. 获取 tag 和 diff
    切换到仓库 ~/code/acme/api。获取后,从 tag v1.4.0 到 HEAD 的 git_log。按 conventional-commit 类型分组。✓ 已复制
    → 分组的 commit 列表
  2. 起草说明
    用 keep-a-changelog 格式编写发布说明,突出破坏性变更和贡献者。✓ 已复制
    → Markdown 更新日志草稿
  3. 标记发布
    使用这些发布说明作为 tag message 创建 tag v1.5.0。对其签名。✓ 已复制
    → 已创建签名 tag

结果: 发布包含准确、易读的说明。

注意事项
  • 提交消息质量差 → 发布说明质量差 — 在此步骤之前在 CI 中强制使用 conventional commits
搭配使用: github

merge 前清理特性分支(压缩 + 改词)

👤 有混乱 WIP 分支的开发者 ⏱ ~15 min intermediate

何时使用: 特性分支上有 14 个提交:'wip'、'fix'、'more fix'、'actually fix it'。在开启 PR 前想压缩成 3 个逻辑提交。

步骤
  1. 检查
    显示分支 'feat/payments' 从 main 分叉以来的 git_log。✓ 已复制
    → 提交列表
  2. 规划压缩
    提出一个 3-commit 重写计划,将相关工作分组。暂不执行。✓ 已复制
    → 包含提交边界和消息的计划
  3. 通过 reset + 新提交执行
    使用 git_reset --soft 执行计划到 merge-base,然后按计划用 git_add + git_commit 分 3 个逻辑块提交。✓ 已复制
    → 3-commit 线性历史

结果: 可审查的 PR 历史。

注意事项
  • 破坏性操作 — 强制推送会覆盖协作者的工作 — 仅在独立特性分支上执行;永远不在共享分支上执行

组合

与其他 MCP 搭配,撬动十倍杠杆

git-2 + github

git_commit + git_push + 在一个流程中开启 PR

用消息 'X' 提交暂存改动,推送,然后在 GitHub 上开启指向 main 的 PR。✓ 已复制
git-2 + filesystem

编辑文件,然后原子提交

编辑 src/index.ts 将 foo 替换为 bar,git_add 该文件,git_commit。✓ 已复制

工具

此 MCP 暴露的能力

工具输入参数何时调用成本
git_status cwd?: str 任何会话的第一步;验证仓库状态 free
git_log cwd?, range?, max_count? 检查历史;使用范围进行发布 diff free
git_diff cwd?, target?, staged?: bool 提交前审查改动 free
git_add cwd?, paths[] 暂存特定文件 — 避免使用 . 以防止敏感文件泄露 free
git_commit cwd?, message, sign?: bool 创建提交;有破坏性,先确认 free
git_branch cwd?, action: list|create|delete|rename, name? 管理分支 free
git_worktree cwd?, action: add|list|remove, path?, branch? 在不切换的情况下处理多个分支 free
git_push cwd?, remote?, branch?, force?: bool 发布提交;force 有破坏性 — 默认为 false network
set_working_directory path: str 切换会话的活跃仓库 free

成本与限制

运行它的成本

API 配额
无 — 全部本地
每次调用 Token 数
git_log/diff 输出可能很大;用 max_count / paths 限制
费用
免费,Apache 2.0
提示
在 git_log 上使用 max_count,在 git_diff 上使用特定路径。大仓库的完整历史日志 = 50k+ 个 token。

安全

权限、密钥、影响范围

最小权限: 本地文件系统对要管理的仓库的访问权限
凭据存储: SSH key 在 ~/.ssh;设置 GIT_BASE_DIR 以沙箱化 MCP
数据出站: git push 发送到已配置的远程
切勿授予: 未确认的情况下强制推送到 main/master

故障排查

常见错误与修复

推送时权限被拒(publickey)

SSH key 对 MCP 进程不可用。启动已加载密钥的 ssh-agent。

验证: ssh -T [email protected]
被拒绝在基目录外的操作

你设置了 GIT_BASE_DIR;请求的路径超出了它。将仓库移到基目录中或扩大范围。

Commit 签名失败

未配置 GPG/SSH 签名密钥。检查 git config --get user.signingkeygpg --list-secret-keys

验证: git commit -S -m test in the repo directly
操作的仓库错误

未设置会话 cwd。总是用 set_working_directory 启动会话或每次调用时传递 cwd。

验证: Call git_status and inspect the returned path

替代方案

git-mcp-server 对比其他方案

替代方案何时用它替代权衡
官方 git MCP你只需要基本的 git 操作,想要参考实现工具较少;无会话 cwd 或签名
GitHub MCP你的工作流是 PR 为中心且在 GitHub 上在 GitHub API 上操作,不是本地 git;互补的

更多

资源

📖 阅读 GitHub 上的官方 README

🐙 查看未解决的 issue

🔍 浏览全部 400+ MCP 服务器和 Skills