git-mcp

A Git MCP server that doesn't suck

Exposes the full Git workflow to any MCP-compatible AI agent — inspect, write, branch, remote, stash, rebase, LFS, git-flow, documentation lookup, and more. Designed to be safe by default, composable, and fast. Powered by simple-git.

Built for coding agents in tools like GitHub Copilot, Claude Code, Cursor, and OpenAI Codex, while remaining compatible with any MCP client that can call tools and resources.

---

Features

• 18 tools with 80+ actions covering everyday Git workflows, advanced recovery, history rewriting, repository analytics, forge pull requests, and external VCS awareness
• Safety-first — destructive operations require explicit confirmation; force push and hook bypass are opt-in via server config
• GPG/SSH signing for commits and tags, with server-level auto-sign support
• Git LFS — track patterns, manage objects, install hooks, migrate history
• Git Flow — drives the git-flow-next CLI, so the finish state machine, conflict recovery, and worktree lifecycle stay correct as the CLI evolves. Preset init, overview, config CRUD, generalized topic actions, and classic feature/release/hotfix/support aliases
• Documentation lookup — search git-scm.com and fetch man pages directly from the LLM
• MCP Resources — URI-addressable read-only views of status, log, branches, and diff
• Bundled agent skill — skills/git-mcp-workflow/ documents MCP-first Git workflows, recovery, worktrees, releases, and advanced operations for AI agents and coding agents; installable via skills-npm and skill.sh
• External VCS awareness — git_but_check / git_jj_check detect GitButler and Jujutsu and guide agents to prefer their native CLIs/MCP (with but teardown guidance) over git-mcp tools when appropriate
• History rewrite — git_rewrite: reword, squash, rewrite-messages, and backup/restore for safe commit-history rewriting
• Repository analytics — git_analytics: contributors, churn, activity, summary, and file-stats computed from local git history
• Pull requests — git_pr: create/list/merge PRs/MRs on GitHub, GitLab, Forgejo, Gitea, and Bitbucket via provider CLI or REST API
• Tangled & Entire awareness — git_tangled_check / git_entire_check detect Tangled hosting and Entire session/context management
• Multi-repo — pass repo_path per-call or configure a server-level default
• Worktrees — git_worktree: plain git worktree by path, or branch-addressed worktrees via git flow worktree with path templates and provenance-aware cleanup
• Cross-platform — macOS, Linux, Windows (Git for Windows), all covered by CI

---

Quick Start

npx (no install)

npx @selfagency/git-mcp --repo-path /path/to/your/repo

Install globally

npm install -g @selfagency/git-mcp
git-mcp --repo-path /path/to/your/repo

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "git": {
      "command": "npx",
      "args": ["-y", "@selfagency/git-mcp", "--repo-path", "/path/to/your/repo"]
    }
  }
}

VS Code (Copilot)

Add to .vscode/mcp.json in your project:

{
  "servers": {
    "git": {
      "command": "npx",
      "args": ["-y", "@selfagency/git-mcp", "--repo-path", "${workspaceFolder}"]
    }
  }
}

---

Configuration

All configuration is via environment variables. Pass them in your MCP client config:

Variable	Default	Description
GIT_REPO_PATH	—	Default repository path (also: --repo-path CLI arg)
GIT_ALLOW_NO_VERIFY	false	Allow --no-verify on commit/push (bypasses hooks)
GIT_ALLOW_FORCE_PUSH	false	Allow --force on push
GIT_ALLOW_FLOW_HOOKS	false	Allow git_flow hooks and filters to execute
GIT_AUTO_SIGN_COMMITS	false	Automatically sign every commit
GIT_AUTO_SIGN_TAGS	false	Automatically sign every tag
GIT_SIGNING_KEY	—	Default GPG key ID or SSH key path
GIT_SIGNING_FORMAT	—	Signing format: openpgp, ssh, or x509
GIT_ALLOW_BUT	false	Enable GitButler awareness (git_but_check)
GIT_ALLOW_JJ	false	Enable Jujutsu awareness (git_jj_check)
GIT_ALLOW_TANGLED	false	Enable Tangled awareness (git_tangled_check)
GIT_ALLOW_ENTIRE	false	Enable Entire awareness (git_entire_check)
BUT_BINARY	but	Override the but executable path
JJ_BINARY	jj	Override the jj executable path
ENTIRE_BINARY	entire	Override the entire executable path
GITHUB_TOKEN	—	GitHub token for git_pr REST fallback
GITLAB_TOKEN	—	GitLab token for git_pr REST fallback
FORGEJO_TOKEN	—	Forgejo/Gitea token for git_pr REST fallback
BITBUCKET_TOKEN	—	Bitbucket token for git_pr REST fallback
GIT_FORGE_PROVIDER	—	Explicit forge provider for self-hosted instances

---

Tool Reference

Tools are grouped by domain. Each root tool takes an action parameter that selects the operation. Where an action is marked as default, omitting action will use it.

Context (git_context)

Action	Description
summary	(default) Full repo snapshot: branch, upstream, pending changes, in-progress operations
search	Search commit history and working tree content
get_config	Read a Git config value
set_config	Write a Git config value
aliases	List all configured git aliases

Status (git_status)

Action	Description
status	(default) Working tree and branch status
diff	Unstaged, staged, or ref-to-ref diff
diff_main	Changes from branch divergence point vs main (or configurable base branch)

History (git_history)

Action	Description
log	(default) Commit log with filtering, pagination, revision ranges, and pathspecs
show	Inspect a single commit
blame	Line-by-line attribution for a file
reflog	Full reflog — the recovery ledger
lg	Compact graph log (--oneline --graph --decorate --all)
who	Contributor shortlog (supports optional file_path)

Commits (git_commits)

Action	Description
add	Stage files or hunks
restore	Discard working tree changes
unstage	Remove files from the staging area
commit	Create a commit with message, signing, and author flags
amend	Amend the last commit without editing the message
wip	Stage all changes and commit with message WIP
revert	Create a revert commit for a given ref
undo	Soft-reset the last commit (reset --soft HEAD~1)
reset	Reset HEAD with configurable mode (soft/mixed/hard)
nuke	Hard-reset the last commit — requires confirm=true

Branches (git_branches)

Action	Description
list	(default) Local and remote branch listing
create	Create a branch
delete	Delete a branch
rename	Rename a branch
checkout	Switch to a branch or ref
set_upstream	Set or update tracking upstream
recent	Recent branches sorted by committer date

Remotes (git_remotes)

Action	Description
list	(default) List configured remotes
manage	Add, remove, or rename a remote
fetch	Fetch from a remote
pull	Pull (fetch + merge/rebase)
push	Push to a remote; force_with_lease supported

Workspace (git_workspace)

Action	Description
stash	Stash and pop/apply/drop/list/show stash entries
stash_all	Stash tracked and untracked changes in one operation
rebase	Start, continue, abort, or skip a rebase
cherry_pick	Apply one or more commits; supports continue/abort/skip
merge	Merge branches with full flag control
bisect	Binary search for a regression (start, good, bad, reset, log)
tag	Create, list, delete, or push tags; supports GPG/SSH signing
worktree	Add, list, remove, lock, unlock, prune, or repair linked worktrees
submodule	Add, update, sync, init, deinit, and list submodules

Git Flow (git_flow)

Drives the git-flow-next CLI, which must be installed and on PATH (brew install git-flow-next, or the releases page). Set GIT_FLOW_BINARY to override the path. When the binary is missing, the tool returns an install hint rather than failing opaquely.

Operation	Description
init	Initialize a repository with git-flow branch conventions
overview	Show the current flow state and active branches
config	Read or write git-flow configuration values
topic	Generalized topic branch action (start, finish, publish, track)
control	Resume or abort an in-progress finish or update

Flags are scoped to the target verb: worktree and worktree_path apply to start and checkout, while keep_worktree and force_worktree apply to finish and delete. A mismatch raises instead of being silently dropped. See the tool reference for the full parameter list.

Worktree (git_worktree)

Two backends. Path-addressed actions drive plain git worktree and need nothing but git; branch-addressed flow_* actions drive git flow worktree, which addresses worktrees by branch name, computes paths from the gitflow.worktreePath template, and tags provenance so cleanup can tell a git-flow-created worktree (removed) from a hand-made one (detached, uncommitted work preserved).

Action	Description
add, list, remove, lock, unlock, prune, repair	Plain git worktree, identified by path
flow_path, flow_add, flow_remove, flow_list	git flow worktree, identified by branch

See the tool reference.

LFS (git_lfs)

Action	Description
track	Add a tracking pattern to .gitattributes
untrack	Remove a tracking pattern
ls-files	List tracked LFS files
status	Show LFS status
pull	Pull LFS objects
push	Push LFS objects
install	Install LFS hooks in the repository
migrate-import	Migrate existing history to LFS
migrate-export	Migrate LFS history back to plain objects

Documentation (git_docs)

Action	Description
search	Search git-scm.com for documentation
man	Fetch and return a Git man page

History Rewrite (git_rewrite)

Action	Description
reword	Change one commit's message (HEAD amends in place; arbitrary via filter-branch)
squash	Combine the last N commits into one (requires confirm=true)
rewrite-messages	Rewrite messages across a range via a SHA→message map (requires confirm=true)
backup	Create a rewrite-backup/<name> branch before rewriting
restore	Hard-reset to a backup branch (requires confirm=true)

Analytics (git_analytics)

Action	Description
contributors	Per-author commits, +/- lines, first/last activity
churn	File hotspots (most commits / most lines changed)
activity	Commit frequency per day
summary	Branch/tag counts, total commits, top contributors, oldest/newest commit
file-stats	File-type breakdown, largest files, recently modified

Pull Requests (git_pr)

Action	Description
create	Create a PR/MR on the detected forge (GitHub, GitLab, Forgejo, Gitea, Bitbucket)
list	List PRs/MRs (state filter)
merge	Merge a PR/MR (method: merge/squash/rebase)

Uses the provider CLI (gh/glab/tea) when installed locally, otherwise the REST API with a *_TOKEN env var. Provider auto-detected from the origin remote; self-hosted instances use GIT_FORGE_PROVIDER.

External VCS Awareness

Tool	Description
git_but_check	Detect GitButler but CLI; prefer but mcp/but, run but teardown before git-mcp tools
git_jj_check	Detect Jujutsu jj CLI and .jj/ management; prefer jj CLI for jj-managed repos
git_tangled_check	Detect Tangled hosting; git transport works, PRs via web UI
git_entire_check	Detect Entire CLI and .entire/ management; use entire for session/context queries

Health Check (git_ping)

Returns server status. Useful for confirming the server is reachable.

---

MCP Resources

URI-addressable read-only snapshots (subscribe-capable):

Resource URI	Content
git+repo://status/{repo_path}	Working tree status (JSON)
git+repo://log/{repo_path}	Recent commit log (JSON)
git+repo://branches/{repo_path}	Branch list (JSON)
git+repo://diff/{repo_path}	Unstaged + staged diff (JSON)

---

Bundled Agent Skill

git-mcp ships a bundled agent skill at skills/git-mcp-workflow/ that teaches any skills-npm-compatible agent to use the MCP tool surface instead of running raw git CLI commands. The skill covers:

• Why LLMs must not use the Git CLI (quoting hazards, silent failures)
• Inspect-before-mutate workflow rules
• Safety order for undo and recovery operations
• Full registered tool surface with action reference
• Workflow playbooks: feature branch, rebase, recovery, worktree, backport, release tagging, Git Flow, merge
• Git concept explanations anchored to MCP tools

Installing the skill

If your agent supports skills-npm:

npm install @selfagency/git-mcp   # or pnpm/yarn
npx skills-npm

Or add to your project's package.json so it runs automatically:

{
  "scripts": {
    "prepare": "skills-npm"
  }
}

Then add to .gitignore:

skills/npm-*

---

Safety

• All mutating tools have destructiveHint: true in their MCP annotations
• git_commits action=reset mode=hard requires confirm=true
• git_commits action=nuke requires confirm=true
• Force push (--force) is disabled unless GIT_ALLOW_FORCE_PUSH=true; force_with_lease is always available
• Hook bypass (--no-verify) is disabled unless GIT_ALLOW_NO_VERIFY=true
• git_flow hook and filter execution is disabled unless GIT_ALLOW_FLOW_HOOKS=true
• Paths are validated against the repository root — traversal attempts are rejected
• Credentials and tokens are never included in responses

---

Development

# Clone and install
git clone https://github.com/selfagency/git-mcp.git
cd git-mcp
pnpm install

# Run in development mode (hot reload)
pnpm dev

# Build
pnpm build

# Run tests
pnpm test

# Type check
pnpm typecheck

# Lint
pnpm lint

# Docs (dev server)
pnpm docs:dev

# Docs (build)
pnpm docs:build

---

License

MIT © Daniel Sieradski