# mcp-server-git: A git MCP server

<!-- mcp-name: io.github.modelcontextprotocol/server-git -->

## Overview

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.

Requires MCP Python SDK 1.x (`mcp>=1.29.0,<2`). SDK 2.0 renamed APIs this server uses. The port to v2 is in progress.

Please note that mcp-server-git is currently in early development. The functionality and available tools are subject to change and expansion as we continue to develop and improve the server.

### Tools

1. `git_status`
   - Shows the working tree status
   - Input:
     - `repo_path` (string): Path to Git repository
   - Returns: Current status of working directory as text output

2. `git_diff_unstaged`
   - Shows changes in working directory not yet staged
   - Inputs:
     - `repo_path` (string): Path to Git repository
     - `context_lines` (number, optional): Number of context lines to show (default: 3)
   - Returns: Diff output of unstaged changes

3. `git_diff_staged`
   - Shows changes that are staged for commit
   - Inputs:
     - `repo_path` (string): Path to Git repository
     - `context_lines` (number, optional): Number of context lines to show (default: 3)
   - Returns: Diff output of staged changes

4. `git_diff`
   - Shows differences between branches or commits
   - Inputs:
     - `repo_path` (string): Path to Git repository
     - `target` (string): Target branch or commit to compare with
     - `context_lines` (number, optional): Number of context lines to show (default: 3)
   - Returns: Diff output comparing current state with target

5. `git_commit`
   - Records changes to the repository
   - Inputs:
     - `repo_path` (string): Path to Git repository
     - `message` (string): Commit message
   - Returns: Confirmation with new commit hash

6. `git_add`
   - Adds file contents to the staging area
   - Inputs:
     - `repo_path` (string): Path to Git repository
     - `files` (string[]): Array of file paths to stage
   - Returns: Confirmation of staged files

7. `git_reset`
   - Unstages all staged changes
   - Input:
     - `repo_path` (string): Path to Git repository
   - Returns: Confirmation of reset operation

8. `git_log`
   - Shows the commit logs with optional date filtering
   - Inputs:
     - `repo_path` (string): Path to Git repository
     - `max_count` (number, optional): Maximum number of commits to show (default: 10)
     - `start_timestamp` (string, optional): Start timestamp for filtering commits. Accepts ISO 8601 format (e.g., '2024-01-15T14:30:25'), relative dates (e.g., '2 weeks ago', 'yesterday'), or absolute dates (e.g., '2024-01-15', 'Jan 15 2024')
     - `end_timestamp` (string, optional): End timestamp for filtering commits. Accepts ISO 8601 format (e.g., '2024-01-15T14:30:25'), relative dates (e.g., '2 weeks ago', 'yesterday'), or absolute dates (e.g., '2024-01-15', 'Jan 15 2024')
   - Returns: Array of commit entries with hash, author, date, and message

9. `git_create_branch`
   - Creates a new branch
   - Inputs:
     - `repo_path` (string): Path to Git repository
     - `branch_name` (string): Name of the new branch
     - `base_branch` (string, optional): Base branch to create from (defaults to current branch)
   - Returns: Confirmation of branch creation

10. `git_checkout`
    - Switches branches
    - Inputs:
      - `repo_path` (string): Path to Git repository
      - `branch_name` (string): Name of branch to checkout
    - Returns: Confirmation of branch switch

11. `git_show`
    - Shows the contents of a commit
    - Inputs:
      - `repo_path` (string): Path to Git repository
      - `revision` (string): The revision (commit hash, branch name, tag) to show
    - Returns: Contents of the specified commit

12. `git_branch`
    - List Git branches
    - Inputs:
      - `repo_path` (string): Path to the Git repository.
      - `branch_type` (string): Whether to list local branches ('local'), remote branches ('remote') or all branches('all').
      - `contains` (string, optional): The commit sha that branch should contain. Do not pass anything to this param if no commit sha is specified
      - `not_contains` (string, optional): The commit sha that branch should NOT contain. Do not pass anything to this param if no commit sha is specified
    - Returns: List of branches

## Installation

### Using uv (recommended)

Install `uv`, then prepare the project environment from the lock file:

```bash
uv --directory /path/to/mcp-server-git sync --locked
```

### Using pip

Alternatively, install the package with pip:

```bash
pip install mcp-server-git
```

## Deployment

This server communicates over stdio. A host service must launch the process and connect its standard input and output to the MCP client. The project does not expose an HTTP endpoint by itself.

### Using uv from the source tree

```bash
uv --directory /path/to/mcp-server-git run --no-sync mcp-server-git --repository /path/to/git/repo
```

`--repository` limits the server to the specified repository and its subdirectories. Omit `--no-sync` if the environment has not been prepared with `uv sync`.

### Using an installed package

```bash
mcp-server-git --repository /path/to/git/repo
```

The equivalent module invocation is:

```bash
python -m mcp_server_git --repository /path/to/git/repo
```

### Docker

Build the image from the project root:

```bash
docker build -t mcp/git .
```

Run it with a repository mounted into the container:

```bash
docker run --rm -i \
  --mount type=bind,src=/path/to/git/repo,dst=/workspace \
  mcp/git --repository /workspace
```

The container also communicates over stdio, so it must be started by an MCP-capable host service.

### Verification

Use the MCP Inspector to verify the stdio server locally:

```bash
npx @modelcontextprotocol/inspector uv --directory /path/to/mcp-server-git run --no-sync mcp-server-git --repository /path/to/git/repo
```

For automated unit tests:

```bash
uv --directory /path/to/mcp-server-git run pytest
```