Skip to main content
Glama
git-mcp-server

git-mcp-server

by jesspig

git-mcp-server

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

快速开始

前置条件

方式一:配置到 opencode(opencode.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 会直接调用对应工具完成。

Related MCP server: GitPilot MCP

配置

环境变量

说明

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

Available Tools

29 tools
git_addA

Stage files into the index, ready for committing. Use this to prepare modified or new files before a commit: select specific files, stage everything (all=True), or tracked changes only (update=True). Does NOT commit — use git_commit for that; review first with git_status and git_diff. Best for: preparing modified or new files before a commit. Returns: 'Staged files:' followed by the staged paths, or 'All changes staged'.

Inputs: all, files, update, repo_path.

git_bisectA

Drive a bisect session: start, mark good/bad commits, or reset. Use this to binary-search which commit introduced a regression by alternating 'good' and 'bad' marks until the culprit is found. Best for: binary-searching which commit introduced a regression. Returns: git bisect progress output. Start with 'start', alternate 'good'/'bad' marks, and 'reset' to end the session. Does NOT inspect history — use git_log to understand commits before bisecting; stash local changes first, because the session checks out commits automatically.

Inputs: commit, operation, repo_path.

git_blameA
Read-onlyIdempotent

Render per-line attribution for a tracked file, optionally restricted to a line range, showing which commit last touched each line. Use this when investigating who changed a line or when a regression was introduced, and to trace how a file evolved. Best for: finding which commit last touched each line of a file. Returns: a line count summary 'Blame for : lines' followed by git blame output with commit hashes, authors and line content; start_line and end_line must be provided together and the file must be tracked by git. Does NOT show current file content or whole-history log — use git_show or git_log for context.

Inputs: file (required), end_line, repo_path, start_line.

git_branchA
Destructive

List, create, or delete branches, marking the current branch with '*'. Use this to review existing branches before choosing where to work, to start a feature branch, or to remove a merged one; in detached HEAD state no branch is current. Does NOT switch branches — use git_checkout for that; does NOT manage release markers — use git_tag. Best for: managing feature branches and listing local or remote branches. Returns: branch listing lines, or confirmation text for create/delete; delete requires confirmed=True and refuses the current branch; force=True replaces an existing branch on create; 'list' with all=True also shows remote branches.

Inputs: all, name, force, confirmed, +2 more.

git_checkoutA
Destructive

Switch to an existing branch, tag, or commit, optionally creating a branch first. Use this to move between branches for different features, to jump to a tag or historical commit, or to start a new branch with create_branch. Does NOT discard local changes without confirmation: force=True discards them and requires confirmed=True — run preview=True first to see what would be discarded, or git_stash to keep changes. Best for: moving between branches to work on different features. Returns: 'Switched to branch ' on success, or an impact preview when preview=True; use git_branch to list what is available to switch to.

Inputs: force, target, preview, confirmed, +2 more.

git_cherry_pickA
Destructive

Apply the changes of one or more commits onto the current branch, optionally without committing (no_commit=True). Use this to port a specific fix or feature from another branch when a full merge is too broad — answering 'how do I copy just this commit?'. Does NOT integrate a whole branch — use git_merge or git_rebase for that; use git_revert to undo a commit instead of applying it. Best for: porting specific commits to another branch. Returns: 'Cherry-picked ' on success; conflicts are reported as errors — resolve them and continue.

Inputs: commits (required), no_commit, repo_path.

git_cleanA
Destructive

Delete untracked files, or preview them first with dry_run. Use this to remove build artifacts and other untracked clutter, and to answer 'what junk is in this repo?' before deleting. DESTRUCTIVE: requires confirmed=True to delete; dry_run=True previews without deleting, so preview first. Does NOT touch tracked files, ignored files, or stashes — untracked files only; use git_status to see untracked files before deciding what to clean. Best for: removing build artifacts and other untracked clutter. Returns: list of removed or would-be-removed files, or 'No untracked files to clean.'

Inputs: dry_run, confirmed, repo_path, directories.

git_cloneA

Clone a remote repository from url into local_path, optionally pinning a branch or shallow depth. Use this when starting work on an existing project, when a full history is not needed (depth), or when a local copy must be created from a remote. Does NOT initialize a new empty repository — use git_init for that. Best for: fetching an existing repository to work on locally. Returns: confirmation text with the local path; refuses non-empty destinations, so the target must be missing or empty.

Inputs: url (required), depth, branch, local_path.

git_commitA

Create a commit with the given message, or amend the last one. Use this when staged changes are ready to record, to fix the previous commit's message or contents (amend=True), or to skip pre-commit hooks (no_verify=True). Does NOT stage files — run git_add first; check git_status if nothing appears staged. Best for: recording staged changes after git_add. Returns: confirmation with the new commit hash, or 'No changes to commit' with a staging hint when untracked files are present.

Inputs: message (required), amend, no_verify, repo_path.

git_configA
Read-onlyIdempotent

Read git configuration values from the repository, either one key or the full list. Use this to verify settings like user.name, user.email, core options, or remote URLs before operating, and to answer 'what is this repo configured to?'. Does NOT modify configuration — it is read-only; use git_remote for a friendlier view of remote URLs. Best for: checking settings like user.name, user.email, remote URLs or core options before operating. Returns: the value of the requested config key, or the full 'git config --list' output when key is omitted; an unset key returns 'Config key ... is not set.' without error.

Inputs: key, repo_path.

git_diffA
Read-onlyIdempotent

Show differences between the working tree, the index, and commits. Defaults to a diffstat summary; pass stat=False for the full diff. Use this to review what a change actually contains before staging or committing, to compare two commits with source and target, or to check what would be committed with staged=True. Best for: reviewing changes before staging or committing. Returns: 'Diff output:' followed by the diff, or 'No changes'; stat=True shows a summary only. Does NOT show file status or history — use git_status for the file list and git_log for commits; use git_show to see one commit's full patch.

Inputs: stat, source, staged, target, +1 more.

git_fetchA

Fetch refs from a remote (default origin) without merging, updating remote-tracking branches. Use this to see upstream changes before deciding to integrate them — answering 'what is on the remote?' — and to prune stale branches with prune=True. Does NOT change the working tree — use git_pull to fetch and integrate, or git_push to send local commits. Best for: updating remote-tracking branches before reviewing upstream changes. Returns: 'Fetched N refs from 'origin'.' followed by per-ref lines; use git_log or git_diff to inspect what was fetched.

Inputs: tags, prune, remote, repo_path.

git_grepA
Read-onlyIdempotent

Search tracked files for a pattern, returning 'file:line:content' matches. Use this to find where a string or symbol appears in the codebase — answering 'where is X used?' — without a shell. Best for: finding where a string appears in the codebase. Returns: 'file:line:content' matches, or 'No matches'. Pattern must not start with '-'; does NOT search commit messages or untracked files — use git_log with its grep filter for commit messages.

Inputs: pattern (required), files, repo_path.

git_initA

Initialize a new git repository in repo_path, creating the directory if missing. Use this when starting a brand-new project, when the working directory is not yet version-controlled, or when a repo needs a non-standard initial branch or bare layout. Does NOT clone existing projects — use git_clone to fetch a remote repository instead. Best for: creating a fresh repository before first commit. Returns: confirmation text with the repository path; refuses non-empty directories, so pass an empty or missing target. More direct than raw git init because it validates the target directory first.

Inputs: bare, repo_path, initial_branch.

git_logA
Read-onlyIdempotent

Show recent commits as ' - ' lines, filtered by author, date range, or message grep. Use this to answer 'what changed recently?', to review history before branching or merging, and to find a commit by author or message text. Best for: reviewing commit history and filtering by author, date or message. Returns: one formatted line per commit, or 'No commits found.' Does NOT show commit patches or file contents — use git_show for a single commit's details and git_grep to search file contents; use git_reflog to see HEAD movements.

Inputs: grep, since, until, author, +2 more.

git_mergeA
Destructive

Merge a branch into the current branch, integrating its commits with or without a merge commit. Use this to bring a feature branch back into its base when histories have diverged, or to squash a branch's work into one commit with squash=True. Does NOT rewrite the current branch's history — use git_rebase for that; use git_cherry_pick to port specific commits instead of a whole branch. Best for: integrating a feature branch back into the base branch. Returns: git merge output text; conflicts raise a ValueError with details — resolve them and retry.

Inputs: branch (required), squash, repo_path, no_fast_forward.

git_pullA

Pull from a remote and merge (or rebase) into the current branch. Use this to sync local work with upstream changes, with rebase=True to keep a linear history instead of a merge commit. Does NOT fetch only — use git_fetch to update tracking branches without touching the working tree; conflicts are reported as errors, resolve and retry. Best for: syncing local work with upstream changes. Returns: 'Pulled from 'origin'.' followed by per-ref lines.

Inputs: branch, rebase, remote, repo_path.

git_pushA
Destructive

Push commits to a remote (default origin), optionally including tags. Use this to publish local commits when work is ready to share, and to push tags for releases; force=True overwrites remote history and requires confirmed=True, tags=True also pushes tags. Does NOT integrate upstream work — if the remote has diverged, use git_fetch or git_pull first. Best for: publishing local commits to the remote repository. Returns: 'Pushed to 'origin'.' followed by per-ref lines; use git_remote to check where the push will go.

Inputs: tags, force, branch, remote, +2 more.

git_rebaseA
Destructive

Rebase the current branch onto an upstream, or manage an in-progress rebase with mode='continue', 'abort', or 'skip'. Use this to keep a feature branch up to date with its base and produce a linear history. Does NOT create a merge commit — use git_merge to record integration; on conflict, resolve and call with mode='continue', or mode='abort' to cancel. Best for: keeping a feature branch up to date with its base. Returns: confirmation text or git rebase output; use git_log afterwards to see the rewritten history.

Inputs: mode, upstream, repo_path.

git_reflogA
Read-onlyIdempotent

Show the reflog for a ref (default HEAD), recording every local HEAD movement even after branch deletions or resets. Use this to recover lost commits after a reset or branch delete, and to answer 'where was HEAD before?'. Best for: recovering lost commits and understanding HEAD history. Returns: 'Showing reflog entries for .' followed by reflog text, or 'No reflog entries found.'; pass ref to inspect a specific branch. Does NOT show regular commit history — use git_log for that; pair with git_reset to restore a commit found here.

Inputs: ref, max_count, repo_path.

git_remoteA
Destructive

Manage remotes: list, add, remove or rename them. Use this to answer 'where does this repo sync to?', to configure a new upstream, or to fix a remote URL. Best for: configuring where the repository syncs to and from. Returns: one 'name -> url' line per remote, or operation confirmation; 'No remotes configured.' when none exist; add needs both name and url, remove/rename operate on existing remotes. Does NOT transfer data — use git_fetch, git_pull, or git_push to move commits. More readable than raw git config --list when looking for remote URLs.

Inputs: url, name, operation, repo_path.

git_resetA
Destructive

Reset the repository to a target commit (default HEAD) in soft, mixed, or hard mode. Use this to undo commits, unstage changes, or discard working tree changes. DESTRUCTIVE: requires confirmed=True to execute; run preview=True first to see which tracked changes would be discarded (hard/mixed modes), while soft mode only moves HEAD and touches neither the working tree nor the index. Does NOT create a new commit — use git_revert to undo a published commit safely, or git_stash to keep changes before resetting. Best for: undoing commits or unstaging changes. Returns: 'Reset () to .' on success, or an impact preview when preview=True.

Inputs: mode, target, preview, confirmed, +1 more.

git_revertA
Destructive

Revert a commit by creating a new commit that undoes it, or apply the undo without committing (no_commit=True). Use this to safely undo a published commit without rewriting history, when other people may already have the commit. Does NOT move HEAD backwards or discard history — use git_reset for that; use git_cherry_pick to re-apply a commit instead of undoing it. Best for: safely undoing a published commit without rewriting history. Returns: confirmation with the new revert commit hash.

Inputs: commit (required), no_commit, repo_path.

git_showA
Read-onlyIdempotent

Render a commit's metadata and patch, defaulting to HEAD. Use this to inspect exactly what a specific commit changed — answering 'what did this commit do?' — or to view the latest change by omitting object. Best for: inspecting what a specific commit changed. Returns: a summary line ' , : ', followed by the commit header and its diff; stat defaults to True and shows a diffstat summary only. Does NOT list history — use git_log to find commits; does NOT compare working tree changes — use git_diff for that.

Inputs: stat, object, repo_path.

git_stashA
Destructive

Manage stashes: list, push changes, or pop and drop existing stashes. Use this to set aside uncommitted work before switching branches, or to restore previously stashed work. Does NOT discard changes permanently — push preserves them for later; only drop, which requires confirmed=True, removes a stash, and push needs modified tracked files. Best for: setting aside work-in-progress to switch context. Returns: stash listing, or git stash output. Use git_checkout after stashing to switch branches; use git_reset to discard changes instead of preserving them.

Inputs: message, confirmed, operation, repo_path, +1 more.

git_statusA
Read-onlyIdempotent

Show the repository's working tree state: current branch, staged, modified and untracked files. Use this at the start of any edit task to answer 'what changed?', and before committing to verify what will be staged. Best for: inspecting repository state before starting edits or after a change. Returns: 'On branch .' first line, then non-empty sections 'Staged changes (N): ' / 'Modified (N): ' / 'Untracked (N): ' with file lists capped at 10 plus ', and N more', or 'Working tree clean on .' when nothing changed; short=True gives compact '--short --branch' output, include_untracked=False omits untracked files. Does NOT show file contents or diffs — use git_diff for those; does NOT list commit history — use git_log. More direct than raw git status because output is returned as text with no shell.

Inputs: short, repo_path, include_untracked.

git_submoduleA

Manage submodules: show status, add a new one, or update all of them. Use this when a repository embeds external repositories, to check whether embedded repos are in sync, or to add a new dependency as a submodule. Best for: embedding and syncing external repositories. Returns: submodule status output, or git submodule output; 'No submodules found.' when none are configured. add needs both url and path; update fetches and inits all submodules. Does NOT clone the superproject — use git_clone for that.

Inputs: url, path, operation, repo_path.

git_tagA
Destructive

Manage tags: list them, create a new one, or delete one. Use this to mark release points in history so commits are easy to reference later, or to list existing releases. Does NOT branch or switch — tags are lightweight markers: use git_branch for branches and git_checkout to switch to a tag. Best for: marking release points in history. Returns: tag names for list, or confirmation for create/delete; delete requires confirmed=True; annotated=True needs a message.

Inputs: message, tag_name, annotated, confirmed, +2 more.

git_worktreeA
Destructive

Manage linked worktrees: list, add, or remove them. Use this to check out multiple branches simultaneously in separate directories when switching back and forth is disruptive, or to work on a second branch without stashing. Does NOT switch the main working tree — use git_checkout for that; use git_branch to see which branches can be added. Best for: checking out multiple branches simultaneously. Returns: worktree listing, or git worktree output; remove requires confirmed=True and add refuses non-empty paths.

Inputs: branch, confirmed, operation, repo_path, +1 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 29 tools

    Disambiguation5/5

    Each of the 29 tools maps to a distinct git subcommand with explicit 'Does NOT' notes that prevent confusion. Even closely related operations like git_reset vs git_revert, git_merge vs git_rebase, and git_fetch vs git_pull have clearly separated purposes, leaving no ambiguity about which tool to use.

    Naming Consistency5/5

    All tools follow a consistent git_<command> pattern using lowercase snake_case, directly mirroring the underlying git subcommand names. There is no mixing of styles (camelCase, abbreviations, or inconsistent verbs), making the naming predictable and easy to infer.

    Tool Count2/5

    At 29 tools, the set exceeds the 25+ threshold and feels heavy for an agent to navigate, especially with niche commands like git_bisect, git_worktree, and git_submodule included. While each tool has a distinct purpose, the sheer number increases selection overhead and may be more than needed for typical workflows.

    Completeness4/5

    The toolbox covers the entire git lifecycle: init/clone, status/add/commit, diff/log/show, branch/merge/rebase, remote/fetch/pull/push, stash/reset/revert, and advanced features like reflog and bisect. Minor gaps exist, such as explicit remote branch deletion, git apply, or garbage collection, but core workflows are fully supported.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      A Model Context Protocol server that provides Git version control operations as structured tools for AI coding agents. It enables LLMs to programmatically manage repositories through actions like committing changes, rolling back code, and comparing diffs.
      10
      Apache 2.0
    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      A lightweight MCP server that enables AI assistants to manage local Git repositories by executing commands like status, add, and commit. It streamlines development workflows by providing repository context and diffs directly to the assistant.
      Apache 2.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that provides tools for interacting with Git repositories, enabling AI assistants to manage repositories, branches, commits, and files through a standardized interface.
      1
      Apache 2.0