/ 目錄 / 演練場 / git-mcp-server
● 社群 cyanheads ⚡ 即開即用

git-mcp-server

作者 cyanheads · cyanheads/git-mcp-server

一個功能完整的 git MCP — 28 個工具,涵蓋 worktree、stash、reflog、GPG 簽署,以及 session 範圍的工作目錄,讓 Claude 能安全地跨多個 repo 進行操作。

相較於官方 git MCP 只涵蓋基本功能,cyanheads/git-mcp-server 走得更深。Worktree 管理、可選的 commit 簽署、路徑沙箱、session 隔離的工作目錄,以及回應格式控制(JSON 適合代理程式,Markdown 適合人類閱讀),使其非常適合多 repo 代理程式與企業工作流程。

為什麼要用

核心特性

即時演示

實際使用效果

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

在相鄰 monorepo 組織的 10 個 repo 中套用相同的重構

👤 平台工程師、開發者關係 ⏱ ~45 min advanced

何時使用: 需要在多個 repo 中升級相依套件或重新命名 import,但不想手動逐一 clone 並切換情境。

前置條件
  • 本地 clone 或寫入權限 — 設定好 SSH 金鑰
步驟
  1. 列舉 repo
    列出 ~/code/acme 底下的所有 repo。對每個 repo 切換工作目錄,執行 git_status,並告訴我目前的分支。✓ 已複製
    → 每個 repo 的狀態資訊
  2. 建立分支並套用變更
    在每個 repo 中,建立分支 'chore/bump-foo',將 package.json 中的 foo 從 1.x 升級至 2.x,以訊息 'chore: bump foo' 提交,推送後(透過 github MCP)開啟 PR。✓ 已複製
    → 每個 repo 的 PR URL

結果: 在一次對話中完成跨 repo 的變更派送。

注意事項
  • Commit 風暴 — 錯誤的重構會同時出現在 10 個 PR 中 — 先在一個 repo 測試,確認無誤後再批量派送
  • 需要 sign-off / DCO 但未簽署 — 啟用 GIT_SIGN_COMMITS 並設定 GIT_USERNAME/GIT_EMAIL
搭配使用: github · filesystem

從兩個 tag 之間的 git log 產生發布說明

👤 發布管理人員 ⏱ ~20 min intermediate

何時使用: 準備發布版本時,希望 changelog 直接從實際的 commit 記錄產生,而非憑記憶撰寫。

步驟
  1. 取得 tag 與 diff
    切換至 repo ~/code/acme/api。執行 fetch,然後用 git_log 取得從 tag v1.4.0 到 HEAD 的記錄,並依 conventional-commit 類型分組。✓ 已複製
    → 分組後的 commit 清單
  2. 草擬發布說明
    以 keep-a-changelog 格式撰寫發布說明,特別標示重大變更與貢獻者。✓ 已複製
    → Markdown 格式的 changelog 草稿
  3. 建立 release tag
    以這份發布說明作為 tag 訊息,建立 tag v1.5.0,並進行簽署。✓ 已複製
    → 已簽署的 tag 建立完成

結果: 發布版本附有準確且易讀的說明。

注意事項
  • Commit 訊息品質低落 → 發布說明同樣品質低落 — 在此步驟之前,先在 CI 中強制執行 conventional commits 規範
搭配使用: github

合併前整理 feature 分支(squash + reword)

👤 有雜亂 WIP 分支的開發者 ⏱ ~15 min intermediate

何時使用: feature 分支上有 14 個 commit:'wip'、'fix'、'more fix'、'actually fix it'。希望在開 PR 前整理成 3 個邏輯清晰的 commit。

步驟
  1. 檢視歷史
    顯示 'feat/payments' 分支自從從 main 分出後的 git_log。✓ 已複製
    → Commit 清單
  2. 規劃 squash 方案
    提出一個將相關工作分組為 3 個 commit 的重寫計畫,先不要執行。✓ 已複製
    → 包含 commit 邊界與訊息的計畫
  3. 透過 reset + 重新提交執行計畫
    使用 git_reset --soft 回到 merge-base,然後依計畫分 3 個邏輯區塊執行 git_add + git_commit。✓ 已複製
    → 線性的 3 個 commit 歷史

結果: 產生一個可供 review 的 PR 歷史記錄。

注意事項
  • 具破壞性 — force-push 會覆蓋協作者的工作 — 僅在個人的 feature 分支上操作;絕不在共用分支上執行

組合

與其他 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 任何 session 的第一步;確認 repo 狀態 free
git_log cwd?, range?, max_count? 查看歷史記錄;發布比對時使用 range 參數 free
git_diff cwd?, target?, staged?: bool 提交前檢視變更內容 free
git_add cwd?, paths[] 暫存特定檔案 — 避免使用 . 以防止敏感檔案外洩 free
git_commit cwd?, message, sign?: bool 建立 commit;具一定破壞性,建議先確認 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 推送 commit;force 具破壞性 — 預設為 false network
set_working_directory path: str 切換 session 目前使用的 repo free

成本與限制

運行它的成本

API 配額
無 — 全部在本地執行
每次呼叫 Token 數
git_log/diff 的輸出可能非常大;請用 max_count / paths 加以限制
費用
免費,Apache 2.0
提示
對 git_log 使用 max_count,對 git_diff 指定特定路徑。在大型 repo 上執行完整歷史 log 可能產生 50k+ token。

安全

權限、密鑰、影響範圍

最小權限: 對你想管理的 repo 具備本地檔案系統存取權限
憑證儲存: SSH 金鑰存放於 ~/.ssh;設定 GIT_BASE_DIR 以沙箱化 MCP
資料出站: git push 會推送至你設定的遠端
切勿授予: Force push to main/master without confirmation

故障排查

常見錯誤與修復

Permission denied (publickey) on push

SSH 金鑰無法被 MCP 程序存取。請啟動 ssh-agent 並載入你的金鑰。

驗證: ssh -T [email protected]
Operation outside base directory rejected

你已設定 GIT_BASE_DIR;請求的路徑超出其範圍。請將 repo 移入基礎目錄,或擴大目錄範圍。

Commit signing fails

GPG/SSH 簽署金鑰未設定。請檢查 git config --get user.signingkeygpg --list-secret-keys

驗證: git commit -S -m test in the repo directly
Wrong repo operated on

Session cwd 未設定。請在 session 開始時執行 set_working_directory,或在每次呼叫時傳入 cwd 參數。

驗證: Call git_status and inspect the returned path

替代方案

git-mcp-server 對比其他方案

替代方案何時用它替代權衡
Official git MCP只需要基本 git 操作,並希望使用官方參考實作工具較少;不支援 session cwd 或簽署功能
GitHub MCP工作流程以 PR 為核心且主要在 GitHub 上進行透過 GitHub API 操作,而非本地 git;兩者可互補搭配使用

更多

資源

📖 閱讀 GitHub 上的官方 README

🐙 查看未解決的 issue

🔍 瀏覽全部 400+ MCP 伺服器和 Skills