Skip to main content
Glama
GitHub MCP Server

GitHub MCP Server

by archish9

VersionControlHelperMCP

A Model Context Protocol (MCP) server providing version control operations as tools for AI coding agents. Built specifically for integration with LangChain deepagents and other MCP-compatible LLM workflows.

What is This?

This MCP server exposes Git version control operations as structured tools that Large Language Models (LLMs) and AI agents can invoke programmatically. Instead of executing raw git commands, an AI coding agent can call typed, validated tools like commit_all_changes, rollback_to_commit, or compare_commits through the standardized MCP protocol.

Why Use This?

Problem

Solution

AI agents generate code without version history

Every code change can be committed automatically

Bad AI-generated code breaks the project

Rollback to any previous commit instantly

No visibility into what the agent changed

Compare any two commits to see exact diffs

Risk of losing work during agent iterations

Branching allows safe experimentation


Related MCP server: git-mcp-server

Installation

Prerequisites

  • Python 3.11+

  • uv package manager

  • Git installed on system

Setup

# Clone the repository
git clone https://github.com/your-repo/VersionControlHelperMCP.git
cd VersionControlHelperMCP

# Install dependencies with uv
uv sync

Running the Server

STDIO Mode (Default)

For local usage with LangChain or other MCP clients:

uv run version-control-helper-mcp

With Default Repository Path

Set REPO_PATH to avoid passing repo_path in every tool call:

REPO_PATH=/path/to/your/project uv run version-control-helper-mcp

Development/Debugging

Use the MCP inspector for testing:

uv run mcp dev src/version_control_helper_mcp/server.py

Available Tools

This server provides 10 tools for complete version control workflows.

1. initialize_repo

Purpose: Initialize a new git repository or verify an existing one.

Parameter

Type

Required

Default

Description

repo_path

string

✅

-

Absolute path to repository directory

initial_commit

boolean

❌

true

Create initial commit with README

Returns: Status message (e.g., "Initialized repository with initial commit: abc1234")

When to Use:

  • Starting a new project from scratch

  • Before any other git operations on a fresh directory

  • Safe to call on already-initialized repos (will return "Already initialized")

Example:

{
  "tool": "initialize_repo",
  "arguments": {
    "repo_path": "/Users/dev/my-project",
    "initial_commit": true
  }
}

2. get_repo_status

Purpose: Check the current state of the repository.

Parameter

Type

Required

Description

repo_path

string

✅

Absolute path to repository

Returns: JSON object with:

  • is_initialized: Whether git is set up

  • current_branch: Active branch name

  • has_changes: Whether there are uncommitted changes

  • staged_files: Files ready to commit

  • modified_files: Changed but unstaged files

  • untracked_files: New files not yet tracked

When to Use:

  • Before committing, to see what will be included

  • After making changes, to verify modifications

  • To check which branch you're on


3. commit_all_changes

Purpose: Stage ALL changes and create a commit in one action.

Parameter

Type

Required

Description

repo_path

string

✅

Absolute path to repository

message

string

✅

Commit message describing changes

Returns: Commit SHA (40-character hash) or "No changes to commit"

Behavior:

  • Automatically runs git add -A (stages everything)

  • Creates commit with provided message

  • Lazy initialization: If repo isn't initialized, initializes it first

When to Use:

  • After generating/modifying code, to save a checkpoint

  • Before risky operations, to have a rollback point

  • At logical milestones during development

Best Practices for Commit Messages:

  • Use conventional format: feat:, fix:, docs:, refactor:, test:

  • Be descriptive: "feat: add user authentication with JWT tokens"

  • Reference the change: "fix: resolve null pointer in login handler"


4. list_commits

Purpose: Retrieve commit history with details.

Parameter

Type

Required

Default

Description

repo_path

string

✅

-

Absolute path to repository

branch

string

❌

"HEAD"

Branch name or "HEAD" for current

limit

integer

❌

50

Maximum commits to return

Returns: JSON with array of commits, each containing:

  • sha: Full 40-char commit hash

  • short_sha: 7-char abbreviated hash

  • message: Commit message

  • author: Author name

  • author_email: Author email

  • timestamp: ISO timestamp

When to Use:

  • To find a commit SHA for rollback

  • To review what changes were made

  • To compare two specific commits


5. rollback_to_commit

Purpose: Reset the repository to a previous commit.

Parameter

Type

Required

Default

Description

repo_path

string

✅

-

Absolute path to repository

commit_sha

string

✅

-

SHA of target commit (full or short)

mode

string

❌

"soft"

Reset mode: soft, mixed, or hard

Reset Modes Explained:

Mode

Staged Changes

Working Directory

Use Case

soft

✅ Preserved

✅ Preserved

Undo last commit, keep changes staged

mixed

❌ Unstaged

✅ Preserved

Undo commit, keep files but unstage

hard

❌ Deleted

❌ Deleted

DANGEROUS: Completely discard all changes

Returns: Message with new HEAD SHA

⚠️ WARNING: hard mode permanently deletes uncommitted changes!

When to Use:

  • Agent generated bad code → rollback to last good commit

  • Want to redo work differently → soft reset

  • Experiment failed → hard reset to clean state


6. compare_commits

Purpose: Show detailed diff between any two commits.

Parameter

Type

Required

Description

repo_path

string

✅

Absolute path to repository

from_commit

string

✅

Source commit SHA (older)

to_commit

string

✅

Target commit SHA (newer)

Returns: JSON with:

  • from_commit, to_commit: The compared SHAs

  • files: Array of changed files, each with:

    • filename: Path to file

    • status: added, modified, deleted, or renamed

    • additions: Lines added

    • deletions: Lines removed

    • patch: Unified diff content

  • total_additions, total_deletions: Summary counts

  • summary: Human-readable summary

When to Use:

  • Review what an agent changed in last iteration

  • Debug regressions by comparing working vs broken states

  • Understand evolution of code over time


7. create_branch

Purpose: Create a new git branch for isolated work.

Parameter

Type

Required

Default

Description

repo_path

string

✅

-

Absolute path to repository

branch_name

string

✅

-

Name for new branch

from_ref

string

❌

Current HEAD

Commit/branch to branch from

Returns: Confirmation message with branch name

When to Use:

  • Before experimental changes, create a feature branch

  • Keep main branch stable while agent experiments

  • Work on multiple features in parallel

Naming Conventions:

  • feature/add-auth - New functionality

  • fix/login-bug - Bug fixes

  • experiment/new-algo - Experimental work


8. switch_branch

Purpose: Switch to a different branch.

Parameter

Type

Required

Description

repo_path

string

✅

Absolute path to repository

branch_name

string

✅

Branch to switch to

Returns: Confirmation of current branch after switch

When to Use:

  • Switch back to main after completing feature

  • Move between different work streams

  • Test code on different branches


9. list_branches

Purpose: Show all branches with current branch indicator.

Parameter

Type

Required

Description

repo_path

string

✅

Absolute path to repository

Returns: Formatted list with * marking current branch:

* main (abc1234): Initial commit
  feature/auth (def5678): Add login page

10. generate_commit_message

Purpose: Auto-generate a commit message based on staged changes.

Parameter

Type

Required

Default

Description

repo_path

string

✅

-

Absolute path to repository

style

string

❌

"conventional"

conventional or simple

Returns: Suggested commit message with change summary

Styles:

  • conventional: Uses prefixes like feat:, fix:, docs:

  • simple: Plain descriptive message


Workflow Examples

Basic Agent Workflow

1. initialize_repo(repo_path="/project")     # Set up version control
2. [Agent generates code...]
3. commit_all_changes(message="feat: initial implementation")
4. [Agent makes more changes...]
5. commit_all_changes(message="fix: resolve edge case")
6. [Something breaks...]
7. list_commits(limit=5)                     # Find last good commit
8. rollback_to_commit(sha="abc1234")         # Restore working state

Safe Experimentation

1. create_branch(branch_name="experiment/new-algo")
2. switch_branch(branch_name="experiment/new-algo")
3. [Agent experiments with risky changes...]
4. commit_all_changes(message="experiment: try new approach")
5. [If successful]
   switch_branch(branch_name="main")
   # Merge logic here
6. [If failed]
   switch_branch(branch_name="main")        # Just abandon the branch

Debugging Workflow

1. list_commits(limit=10)                    # See recent history
2. compare_commits(from="abc", to="def")     # What changed?
3. [Identify the breaking commit]
4. rollback_to_commit(sha="abc", mode="soft")  # Go back, keep changes visible

Dependencies

Package

Version

Purpose

mcp

≥1.26.0

MCP Python SDK for server/tools

gitpython

≥3.1.46

Git repository operations

pygithub

≥2.8.1

GitHub API (future remote ops)

pydantic

≥2.0.0

Structured data models


Architecture

VersionControlHelperMCP/
├── pyproject.toml           # UV project configuration
├── src/version_control_helper_mcp/
│   ├── __init__.py
│   ├── server.py            # MCP server entry point
│   ├── tools.py             # Tool implementations
│   ├── git_utils.py         # GitPython wrapper
│   └── models.py            # Pydantic response models
└── README.md

Error Handling

All tools return clear error messages:

Scenario

Error Message

Git not initialized

"Git repository not initialized. Call initialize_repo first."

Invalid commit SHA

"Invalid commit SHA: [sha]"

Branch not found

"Branch '[name]' not found"

No changes to commit

"No changes to commit"


License

MIT

Available Tools

10 tools
commit_all_changesA

Stage ALL changes (including untracked files) and create a commit.

This tool acts as a "save point" for the project. It performs the equivalent of:

  1. git add -A (Stages all modified, deleted, and new files)

  2. git commit -m "message"

It will automatically initialize the repository if it hasn't been initialized yet.

Args: repo_path: The absolute path to the repository. message: A descriptive commit message. Common prefixes: 'feat:', 'fix:', 'docs:', 'refactor:', 'test:'.

Returns: The SHA (full hash) of the new commit, or a message indicating "No changes to commit" if the working directory was clean.

Inputs: repo_path (required), message (required). Returns: result

compare_commitsA

Compare two commits and return the diff.

This tool generates a detailed comparison between two points in the history (from_commit -> to_commit). It's useful for:

  • Reviewing changes between versions.

  • Debugging when a bug was introduced.

  • Generating a changelog.

The output includes a summary of file changes (added, modified, deleted, renamed) and the actual diff content for each file.

Args: repo_path: The absolute path to the repository. from_commit: The source (older) commit SHA. to_commit: The target (newer) commit SHA.

Returns: A JSON-formatted string containing the list of changed files, additions/deletions counts, and diff patches.

Inputs: repo_path (required), from_commit (required), to_commit (required). Returns: result

create_branchA

Create a new git branch.

This tool creates a new branch pointer but DOES NOT switch to it. To start working on the new branch, you must call switch_branch afterwards.

Args: repo_path: The absolute path to the repository. branch_name: The name of the new branch (e.g., "feature/new-login"). from_ref: The commit SHA or branch name to start the new branch from. If not provided, defaults to the current HEAD.

Returns: A confirmation message containing the new branch name.

Inputs: repo_path (required), branch_name (required), from_ref. Returns: result

generate_commit_messageA

Generate a suggested commit message based on staged changes.

This tool analyzes the staged and modified files to suggest a commit message. Note: This uses a simple heuristic (template-based), not a full LLM analysis of the diff content. It is useful as a starting point or for quick commits.

Styles:

  • "conventional": Uses Conventional Commits format (feat: ..., fix: ..., chore: ...) based on file types.

  • "simple": Returns a plain predictive sentence like "Update 3 files".

Args: repo_path: The absolute path to the repository. style: The message style format to use. Defaults to "conventional".

Returns: A string containing the suggested commit message and a brief summary of detected changes.

Inputs: repo_path (required), style. Returns: result

get_repo_statusA

Get the current status of the git repository.

This tool provides a snapshot of the repository's state, including:

  • Initialization status (is it a git repo?)

  • Current branch name

  • Whether there are uncommitted changes

  • Lists of staged, modified, and untracked files

Use this tool before committing to verify what changes will be included, or to simply check the current context (branch, pending changes).

Args: repo_path: The absolute path to the repository.

Returns: A JSON-formatted string containing the repository status details.

Example JSON structure:
{
  "is_initialized": true,
  "current_branch": "main",
  "has_changes": true,
  "staged_files": ["file1.py"],
  "modified_files": ["file2.py"],
  "untracked_files": ["new_file.py"]
}

Inputs: repo_path (required). Returns: result

initialize_repoA

Initialize a new git repository at the specified path.

This tool creates a .git directory at repo_path if it doesn't already exist. It is safe to call on an existing repository (it will return a success message without modifying the repo).

Args: repo_path: The absolute path to the directory where the git repository should be initialized. If the directory does not exist, it will be created. initial_commit: If True, and the repository is empty or fresh, an initial commit will be created. This includes creating a README.md if one doesn't exist. Default is True.

Returns: A status message indicating whether the repository was initialized, already existed, or if an initial commit was created.

Inputs: repo_path (required), initial_commit. Returns: result

list_branchesB

List all branches in the repository.

Shows all local branches with current branch marked.

Args: repo_path: Path to the repository directory

Returns: JSON list of branches with current branch indicator

Inputs: repo_path (required). Returns: result

list_commitsA

List the commit history for a specific branch or reference.

Retrieves a list of commits starting from the specified branch (or HEAD), going back in history up to limit. Each commit includes:

  • SHA (full and short)

  • Message

  • Author details

  • Timestamp

Args: repo_path: The absolute path to the repository. branch: The branch name, tag, or commit SHA to start listing from. Defaults to "HEAD" (current checkout). limit: The maximum number of commits to return. Defaults to 50.

Returns: A JSON-formatted string containing a list of commit objects.

Inputs: repo_path (required), branch, limit. Returns: result

rollback_to_commitA

Roll back the repository state to a previous commit.

This tool resets the current branch head to commit_sha. The mode determines what happens to the working directory and index:

  • "soft" (Default): Undoes the commit(s) but leaves changes staged in the index. Useful if you want to squash commits or fix the last commit message.

  • "mixed": Undoes the commit(s) and unstages changes, but keeps the files in the working directory. Useful if you want to keep the work but start fresh with staging.

  • "hard": WARNING - Destructive! Resets everything to the state of commit_sha. Any uncommitted changes (staged or unstaged) will be PERMANENTLY LOST. Use this only if you want to discard all work since commit_sha.

Args: repo_path: The absolute path to the repository. commit_sha: The full or short SHA of the commit to revert to. mode: The reset mode: "soft", "mixed", or "hard".

Returns: A message confirming the rollback and the new HEAD SHA.

Inputs: repo_path (required), commit_sha (required), mode. Returns: result

switch_branchA

Switch the repository to a different branch.

This command updates the working directory to match the state of the specified branch. It performs a git checkout.

Args: repo_path: The absolute path to the repository. branch_name: The name of the branch to switch to. The branch must already exist.

Returns: A confirmation message indicating the successful switch and current branch name.

Inputs: repo_path (required), branch_name (required). Returns: result

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 10 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose with no overlap: commit_all_changes (staging and committing), compare_commits (diff analysis), create_branch (branch creation), generate_commit_message (message suggestion), get_repo_status (status overview), initialize_repo (repository initialization), list_branches (branch listing), list_commits (history viewing), rollback_to_commit (state reset), and switch_branch (branch switching). The descriptions clearly differentiate their specific git operations.

    Naming Consistency5/5

    All tools follow a consistent verb_noun pattern with snake_case throughout: commit_all_changes, compare_commits, create_branch, generate_commit_message, get_repo_status, initialize_repo, list_branches, list_commits, rollback_to_commit, and switch_branch. The naming is predictable and follows the same grammatical structure across all tools.

    Tool Count5/5

    With 10 tools, this server is well-scoped for git repository management. Each tool serves a distinct, essential function in the git workflow (initialization, status checking, branching, committing, history viewing, comparison, and rollback). The count is neither too sparse nor bloated, covering core operations without redundancy.

    Completeness4/5

    The toolset provides comprehensive coverage of git operations including initialization, status monitoring, branching, committing, history viewing, diff comparison, and rollback. Minor gaps exist such as missing tools for merging branches, handling remotes (push/pull), or managing tags, but core workflows are well-supported and agents can accomplish most common tasks.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      B
      maintenance
      A Model Context Protocol server for Git repository interaction and automation. This server provides tools to read, search, and manipulate Git repositories via Large Language Models.
      14
      97,509 PyPI
      91,952
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      A Model Context Protocol server that enables Large Language Models to interact with Git repositories through a robust API, supporting operations like repository initialization, cloning, file staging, committing, and branch management.
      28
      4,204 npm
      245
      Apache 2.0
    • A
      license
      B
      quality
      D
      maintenance
      A Model Context Protocol server that enables LLMs to interact with Git repositories, providing tools to read, search, and manipulate Git repositories through commands like status, diff, commit, and branch management.
      12
      MIT
    • A
      license
      C
      quality
      B
      maintenance
      A Model Context Protocol server that enables LLMs to interact with Git repositories, providing tools to read, search, and manipulate Git repositories through commands like status, diff, commit, and branch operations.
      22
      4
      MIT