git-mcp-server
Provides tools for interacting with Git repositories, enabling AI agents to manage repository status, staging, commits, branches, remotes, and other version control operations.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@git-mcp-server show me the current git status and recent commits"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
git-mcp-server
本地 Git MCP 服务器:将 git 操作封装为 29 个 MCP 工具,供 AI 客户端直接调用。让 AI 像人一样读写仓库——查看状态、暂存提交、查询历史、管理分支与远程,全程无需离开对话。
快速开始
前置条件
系统已安装 git
方式一:配置到 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
配置
环境变量 | 说明 |
|
|
| 是否允许强制推送(默认 false 禁用,设为 true 启用;启用后 force 仍需 confirmed) |
工具一览
共 29 个工具,分 6 大分组:
仓库管理
工具 | 说明 |
| 初始化仓库(可指定初始分支、裸仓库) |
| 克隆远程仓库到本地(支持浅克隆、指定分支) |
| 查看工作区状态(可隐藏未跟踪文件) |
| 删除/预览未跟踪文件(需确认) |
| 读取 git 配置(指定 key 或全量列出) |
暂存与提交
工具 | 说明 |
| 暂存文件(全量/更新/指定文件) |
| 创建提交(支持 amend、no-verify) |
| 查看差异(工作区/暂存区/提交间对比,支持 stat) |
历史查询
工具 | 说明 |
| 查看提交历史(支持作者/日期/消息过滤) |
| 查看提交的元数据与补丁 |
| 逐行追溯文件修改归属(可限定行范围) |
| 查看引用日志 |
| 在跟踪文件中搜索模式 |
分支操作
工具 | 说明 |
| 列出/创建/删除分支(delete 需确认) |
| 切换分支、标签或提交(可先创建新分支) |
| 合并分支到当前分支(冲突返回详情) |
| 变基或管理进行中的 rebase |
| 将指定提交应用到当前分支 |
远程操作
工具 | 说明 |
| 管理远程仓库(list/add/remove/rename) |
| 从远程拉取引用 |
| 拉取并合并(支持 rebase) |
| 推送到远程(force/tags,拒绝时返回详情) |
高级操作
工具 | 说明 |
| 列出/创建/删除标签(annotated 标签需 message) |
| 管理stash(list/push/pop/drop) |
| 重置到指定提交(soft/mixed/hard,需确认) |
| 反向提交(不改变历史) |
| 管理并行工作树(list/add/remove) |
| 二分查找引入 bug 的提交 |
| 管理子模块(status/add/update) |
核心特性
完整的 git 工作流覆盖:从 init/clone 到 bisect/submodule,29 个工具涵盖日常开发全场景
官方 MCP SDK:基于
mcp包标准stdio传输,兼容任意支持 MCP 的客户端;工具契约由 Pydantic schema 定义可自纠的错误反馈:失败时返回
is_error结果及具体信息,调用方 LLM 可据此自行修正只读/破坏性标注:工具标注
readOnlyHint/destructiveHint,客户端可据此给予不同级别的安全提示四层安全防线:路径白名单、防 flag 注入、ref 预校验、破坏性操作显式确认(详见下方)
安全模型
防线 | 机制 |
路径白名单 | 仓库路径经 |
防 flag 注入 | ref / branch / target 等参数拒绝以 |
ref 预校验 |
|
破坏性确认 |
|
只读 vs 破坏性工具分类
只读(8 个):
git_statusgit_diffgit_loggit_showgit_blamegit_refloggit_grepgit_config破坏性(12 个):
git_resetgit_cleangit_revertgit_mergegit_rebasegit_cherry_pickgit_pushgit_branchgit_checkoutgit_stashgit_taggit_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)。
许可
Available Tools
29 toolsgit_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_blameARead-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_branchADestructive
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_checkoutADestructive
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_pickADestructive
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_cleanADestructive
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_configARead-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_diffARead-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_grepARead-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_logARead-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_mergeADestructive
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_pushADestructive
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_rebaseADestructive
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_reflogARead-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_remoteADestructive
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_resetADestructive
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_revertADestructive
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_showARead-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_stashADestructive
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_statusARead-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_tagADestructive
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_worktreeADestructive
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
Scored across 29 tools
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.
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.
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.
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
Related MCP Connectors
AI-native git hosting — repos, PRs, issues, CI gates, and AI code review over MCP (60 tools).
Plain-English git for agents: 22 tools to branch, commit, push and tag. Free tier.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Related MCP Servers
- AlicenseAqualityDmaintenanceA 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.10Apache 2.0
- AlicenseNot gradedqualityNot gradedmaintenanceA 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
- AlicenseNot gradedqualityDmaintenanceAn MCP server that provides tools for interacting with Git repositories, enabling AI assistants to manage repositories, branches, commits, and files through a standardized interface.1Apache 2.0
- FlicenseNot gradedqualityDmaintenanceA local-only MCP server that exposes git repository history, diffs, and status as tools for LLM clients, working entirely against a local git repo on disk.-