MCP Git: Use cases

Commit and push

Commit and push a change.

A README change is ready to make in a clean checkout; you want it recorded and published without pushing the shared develop branch.

Illustrative conversation

YouCommit README.md with a conventional message on a new branch and push it.

Tool callgit_branch { "action": "create", "name": "feature/setup-guide" }

Tool callgit_branch { "action": "checkout", "name": "feature/setup-guide" }

What happensThe branch is created from verified local develop and checked out. README.md is then edited.

Tool callgit_inspect {}

What happensOne unstaged path: README.md.

Tool callgit_commit { "subject": "docs(readme): clarify initial setup steps", "bullets": ["explain the first repository check"], "patterns": ["README.md"] }

What happensCommit 4c184909, with the full id, author and timestamp.

Tool callgit_remote { "action": "push", "remote": "origin", "branch": "feature/setup-guide" }

What happens{ "pushed": true }

AgentThe branch is on origin and refs/heads/feature/setup-guide is 4c184909, the id of my commit.

If a response is lost, inspect the history before you commit again, because a repeat can create a second commit. See commit and push.

Refusals

Keep a branch from reaching develop by accident.

You do not fully trust a prompt, a script or a tired afternoon with the shared branches.

Illustrative conversation

YouPush my work to develop.

Tool callgit_remote { "action": "push", "remote": "origin", "branch": "develop" }

What happensTool error: "operation requires user handoff: push to protected branch ('develop' is a protected branch; direct push is not allowed)".

YouCommit it with the message "fixed it".

Tool callgit_commit { "subject": "fixed it", "patterns": ["README.md"] }

What happensTool error: "operation requires user handoff: commit (commit message does not follow conventional commits format)".

AgentBoth were refused. I will push a feature branch instead, and use a subject such as "docs(readme): clarify setup steps".

A refusal can arrive as a plain error or as a successful answer that says it is an error, so an agent checks both. A rejected commit message can leave the files staged: look before you try again.

Rebase

Rebase onto develop.

A feature branch has fallen behind the latest shared work.

Illustrative conversation

YouRebase this branch onto develop and tell me about conflicts.

Tool callgit_remote { "action": "fetch", "remote": "origin" }

What happens{ "fetched": "origin" }

Tool callgit_rebase { "action": "plan" }

What happensUpstream origin/develop and one commit to replay, 4c184909, "docs(readme): clarify initial setup steps", suggested as pick.

Tool callgit_rebase { "action": "start", "plan": [ { "commit_id": "4c184909", "action": "pick" } ] }

What happens{ "type": "completed", "operations": 1, "final_commit": "c0c5480b" }

Tool callgit_log { "max_count": 3 }

What happensThe branch now has my commit on top of "docs: add notes", the commit someone else pushed to develop meanwhile.

Tool callgit_remote { "action": "push", "remote": "origin", "branch": "feature/setup-guide" }

What happensTool error: "push to remote 'origin' failed". The remote still has the old commit and the rebased branch is not a fast-forward of it.

AgentThe rebase finished with no conflicts. I could not push the rewritten branch because MCP Git has no force push; tell me how you want to publish it.

See rebase onto develop.

History and diff

Read history and a diff without flooding the conversation.

You want to know what a branch changes compared with the shared develop branch, and who touched it last.

Illustrative conversation

YouWhat does this branch change compared with origin/develop?

Tool callgit_diff { "from": "origin/develop", "to": "HEAD" }

What happensOne file, README.md, modified: two lines added (a blank line and "Run the first repository check before you start."). total_files 1, returned_lines 5, truncated false.

Tool callgit_log { "max_count": 3 }

What happensUp to three commits from the returned history, each with id, author, summary and timestamp.

AgentThe branch adds two lines to README.md and nothing else. The diff was complete: truncated is false.

A difference that was cut short is incomplete evidence, so an agent narrows the range or the files rather than trusting it.

Submodules

Work across a repository and its submodules.

You want to pin a library to a specific version inside a project, so everyone gets the same one.

Illustrative conversation

YouAdd this library as a submodule at v1.2.3 and record it.

Tool callgit_repo { "action": "submodule_add", "url": "https://example.com/org/library.git", "path": "vendor/library", "ref": "v1.2.3" }

What happensThe submodule is added and checked out at the tag.

Tool callgit_repo { "action": "submodule_list" }

What happensOne entry, vendor/library, at the commit the tag points to.

Tool callgit_commit { "subject": "build(deps): add library at v1.2.3", "patterns": [".gitmodules", "vendor/library"] }

What happensOne commit records the file and the path together.

AgentThe parent pins vendor/library at v1.2.3 in a single commit.

A failed clone or addition can leave files behind, so inspect before you delete anything. See repositories and submodules.

Shared service

Run it as a shared service.

Several trusted programs on your machine should share one checkout through one server.

Illustrative conversation

YouStart MCP Git on a private socket and confirm it serves the right repository.

What happensShell commands create the private directory with install -d -m 700 "$HOME/.local/run/mcp-git", then start mcp-git serve --transport unix --socket "$HOME/.local/run/mcp-git/server.sock" in the repository root.

Tool callgit_inspect {}

What happensThe branch and clean state of the repository the server was started in.

AgentThe server is up on a private socket and it is serving the checkout you named. Remember that every client shares its staging area.

After a lost response, inspect the repository and the remote before repeating a write. See shared service setup.