home / mcp / github mcp server

GitHub MCP Server

Provides version control operations as MCP tools, enabling AI agents to manage Git repositories safely and programmatically.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "archish9-github-mcp-small": {
      "command": "uv",
      "args": [
        "run",
        "github-mcp"
      ],
      "env": {
        "REPO_PATH": "/path/to/your/project"
      }
    }
  }
}

A Git-based MCP Server exposes version control operations as structured tools you can call from AI agents. It lets you manage repositories, commits, branches, and diffs without running raw Git commands, enabling safer, validated interactions in your MCP workflows.

How to use

You will interact with the server by starting it in STDIO mode and then invoking the provided tools from your MCP client or LangChain-based agents. Each tool corresponds to a Git operation and returns structured results, such as commit SHAs, status summaries, or diff details. You can automate common workflows like initializing a repo, creating commits from generated code, reviewing history, and safely exploring experimental changes via branches.

How to install

Prerequisites: You need Python 3.11 or newer, the uv package manager, and Git installed on your system.

Step 1: Clone the MCP server repository.

git clone https://github.com/your-repo/github-mcp-small.git

Step 2: Change into the project directory.

cd github-mcp-small

Step 3: Install dependencies and prepare the environment using the UV tooling.

uv sync

Run the MCP server

To run locally in STDIO mode for use with LangChain or other MCP clients, start the server with the following command.

uv run github-mcp

Run with a default repository path

If you want to avoid passing the repository path for every tool call, set the default repository path in the environment before starting the server.

REPO_PATH=/path/to/your/project uv run github-mcp

Development and debugging

If you need to test MCP internals or inspect the server while developing, you can invoke the MCP inspector. This helps you validate tool behavior during development.

uv run mcp dev src/github_mcp/server.py

Available tools

initialize_repo

Initialize a new Git repository or verify an existing one. It accepts a repository path and an optional initial commit flag to create an initial commit.

get_repo_status

Retrieve the current status of the repository, including whether it is initialized, the active branch, and lists of staged, modified, and untracked files.

commit_all_changes

Stage all changes in the repository and create a commit with a provided message. If the repository is not initialized, it will be initialized automatically.

list_commits

Return a list of commits from a specified branch (defaulting to HEAD), including SHAs, messages, authors, and timestamps.

rollback_to_commit

Reset the repository to a specified commit SHA using soft, mixed, or hard modes with a clear safety warning for hard resets.

compare_commits

Show a detailed diff between two commits, including per-file changes, patch content, and a summary of additions and deletions.

create_branch

Create a new branch from a given reference (defaults to the current HEAD) to isolate work.

switch_branch

Switch the working context to a specified branch and confirm the current branch.

list_branches

List all branches with an indicator for the currently active one, along with brief descriptions.

generate_commit_message

Auto-generate a commit message based on the current staged changes, with options for conventional or simple styles.