GIT MCP Server

TypeScript

Model Context Protocol

Version

License

Status

GitHub

A Model Context Protocol (MCP) server that provides tools for interacting with Git repositories. This server allows AI assistants and LLM agents to manage repositories, branches, commits, and files through a standardized interface without requiring direct filesystem or command-line access. It exposes Git operations as MCP resources and tools, leveraging the simple-git library for core functionality while maintaining proper security boundaries.

Overview

Key capabilities:

Repository Management: Initialize, clone, and check repository status
Branch Operations: Create, list, checkout, delete, and merge branches
Working Directory: Stage files, commit changes, create diffs
Remote Operations: Add remotes, fetch, pull, push
Advanced Git Commands: Manage tags, stash changes, cherry-pick, rebase

Architecture & Components

Core system architecture:

<details> <summary>Click to expand Mermaid diagram</summary>

flowchart TB
    subgraph API["API Layer"]
        direction LR
        MCP["MCP Protocol"]
        Val["Validation (Zod)"]

        MCP --> Val
    end

    subgraph Core["Core Services"]
        direction LR
        GitService["Git Service (simple-git)"]
        ErrorService["Error Service"]

        GitService <--> ErrorService
    end

    subgraph Resources["Resource Layer"]
        direction LR
        Repo["Repository Resources"]
        Diff["Diff Resources"]
        File["File Resources"]
        History["History Resources"]

        Repo <--> Diff
        Repo <--> File
        Repo <--> History
    end

    subgraph Tools["Tool Layer"]
        direction LR
        RepoTools["Repository Tools"]
        BranchTools["Branch Tools"]
        WorkdirTools["Working Directory Tools"]
        RemoteTools["Remote Tools"]
        AdvancedTools["Advanced Tools"]

        RepoTools <--> BranchTools
        BranchTools <--> WorkdirTools
        WorkdirTools <--> RemoteTools
        RemoteTools <--> AdvancedTools
    end

    Val --> GitService
    GitService --> Resources
    GitService --> Tools

    classDef layer fill:#2d3748,stroke:#4299e1,stroke-width:3px,rx:5,color:#fff
    classDef component fill:#1a202c,stroke:#a0aec0,stroke-width:2px,rx:3,color:#fff
    classDef api fill:#3182ce,stroke:#90cdf4,stroke-width:2px,rx:3,color:#fff
    classDef core fill:#319795,stroke:#81e6d9,stroke-width:2px,rx:3,color:#fff
    classDef resource fill:#2f855a,stroke:#9ae6b4,stroke-width:2px,rx:3,color:#fff
    classDef tool fill:#805ad5,stroke:#d6bcfa,stroke-width:2px,rx:3,color:#fff

    class API,Core,Resources,Tools layer
    class MCP,Val api
    class GitService,ErrorService core
    class Repo,Diff,File,History resource
    class RepoTools,BranchTools,WorkdirTools,RemoteTools,AdvancedTools tool

</details>

Core Components:

MCP Server (server.ts): Uses the @modelcontextprotocol/sdk to create a server exposing resources and tools.
Git Service (services/git-service.ts): Abstraction layer over the simple-git library providing clean interfaces for Git operations.
Resources (resources/): Expose Git data (like status, logs, file content) through MCP resources with consistent URI templates.
Tools (tools/): Expose Git actions (like commit, push, pull) through MCP tools with well-defined input schemas (validated using Zod).
Error Handling (services/error-service.ts): Standardized error handling and reporting for Git and MCP operations.
Entry Point (index.ts): Initializes and starts the server, connecting it to the standard I/O transport.

Features

Resource Access

Expose Git repository information through MCP resources:

Repository Information: Access basic Git repository information including current branch, status, and reference details
Repository Branches: List all branches in the repository with current branch indicator
Repository Remotes: List all configured remote repositories with their URLs
Repository Tags: List all tags in the repository with their references
File Content: Access content of specific files at a given Git reference
Directory Listing: View lists of files and directories at a specific path and reference
Diffs: Get differences between references, unstaged changes, or staged changes
Commit History: View detailed commit logs with author, date, and message information
File Blame: See line-by-line attribution showing which commit last modified each line
Commit Details: Access detailed information about specific commits including diff changes

Git Operations

Execute Git commands through MCP tools:

Repository Operations: Initialize repositories, clone from remotes, check repository status
Branch Operations: Create branches, list branches, checkout, delete branches, merge
Working Directory Operations: Stage files, unstage files, commit changes, create diffs
Remote Operations: Add remotes, list remotes, fetch, pull, push
Advanced Operations: Manage tags, stash changes, cherry-pick commits, rebase branches, reset, clean

Installation

Prerequisites

Node.js 16 or higher
Git installed and available in the PATH

Install from NPM

npm install -g @cyanheads/git-mcp-server

Install from Source

git clone https://github.com/cyanheads/git-mcp-server.git
cd git-mcp-server
npm install
npm run build

Usage

Running the Server

If installed globally via NPM:

git-mcp-server

If running from source:

node build/index.js

The server communicates through stdin/stdout using the Model Context Protocol, making it compatible with any MCP client.

Integration with Claude

Add to your Claude configuration file (e.g., cline_mcp_settings.json or claude_desktop_config.json):

{
  "mcpServers": {
    "git": {
      "command": "git-mcp-server", // Or the full path to build/index.js if not installed globally
      "args": [],
      "env": {},
      "disabled": false,
      "autoApprove": [] // Configure auto-approval rules if desired
    }
  }
}

Integration with Other MCP Clients

Use the MCP inspector to test the server:

# If installed globally
npx @modelcontextprotocol/inspector git-mcp-server

# If running from source
npx @modelcontextprotocol/inspector build/index.js

Project Structure

The codebase follows a modular structure:

git-mcp-server/
├── src/
│   ├── index.ts           # Entry point: Initializes and starts the server
│   ├── server.ts          # Core MCP server implementation and setup
│   ├── resources/         # MCP Resource implementations
│   │   ├── descriptors.ts # Resource URI templates and descriptions
│   │   ├── diff.ts        # Diff-related resources (staged, unstaged, commit)
│   │   ├── file.ts        # File content and directory listing resources
│   │   ├── history.ts     # Commit history and blame resources
│   │   ├── index.ts       # Aggregates and registers all resources
│   │   └── repository.ts  # Repository info, branches, remotes, tags resources
│   ├── services/          # Core logic and external integrations
│   │   ├── error-service.ts # Centralized error handling utilities
│   │   └── git-service.ts   # Abstraction layer for simple-git operations
│   ├── tools/             # MCP Tool implementations
│   │   ├── advanced.ts    # Advanced Git tools (tag, stash, cherry-pick, rebase, log, show)
│   │   ├── branch.ts      # Branch management tools (list, create, checkout, delete, merge)
│   │   ├── index.ts       # Aggregates and registers all tools
│   │   ├── remote.ts      # Remote interaction tools (add, list, fetch, pull, push)
│   │   ├── repository.ts  # Repository level tools (init, clone, status)
│   │   └── workdir.ts     # Working directory tools (add, reset, commit, diff, reset-commit, clean)
│   ├── types/             # TypeScript type definitions
│   │   └── git.ts         # Custom types related to Git operations
│   └── utils/             # Shared utility functions
│       ├── global-settings.ts # Manages global working directory setting
│       └── validation.ts  # Input validation schemas (Zod) and helpers
├── build/                 # Compiled JavaScript output
├── docs/                  # Documentation files
├── logs/                  # Log files (if any)
├── scripts/               # Helper scripts for development (e.g., clean, tree)
├── .env.example           # Example environment variables
├── .gitignore             # Git ignore rules
├── LICENSE                # Project license file
├── package.json           # Project metadata and dependencies
├── package-lock.json      # Lockfile for dependencies
├── README.md              # This file
└── tsconfig.json          # TypeScript compiler configuration

Tools

Git MCP Server provides a comprehensive suite of tools for Git operations:

Repository Operations

| Tool | Description | | ------------ | ------------------------------------------------------------------------------------------------ | | git_init | Initialize a new Git repository at the specified path with options for bare repositories. | | git_clone | Clone a Git repository from a remote URL to a local path with branch and depth options. | | git_status | Get the current status of a Git repository including working directory and staging area changes. |

Branch Operations

| Tool | Description | | ------------------- | ---------------------------------------------------------------------------------------------- | | git_branch_list | List all branches in a repository with options to include remote branches. | | git_branch_create | Create a new branch with options for specifying the starting point and automatic checkout. | | git_checkout | Checkout a branch, tag, or commit with options to create a new branch during checkout. | | git_branch_delete | Delete a branch with options for force deletion of unmerged branches. | | git_merge | Merge a branch into the current branch with customizable commit messages and merge strategies. |

Working Directory Operations

| Tool | Description | | ------------------- | ----------------------------------------------------------------------------------------------- | | git_add | Stage files for commit with support for individual files or entire directories. | | git_reset | Unstage files from the staging area with options for specific files or all staged changes. | | git_commit | Commit staged changes with customizable commit messages, author information, and amend options. | | git_diff_unstaged | Get a diff of all unstaged changes in the working directory with options for specific files. | | git_diff_staged | Get a diff of all staged changes in the index with options for specific files. | | git_reset_commit | Reset the repository to a specific reference with options for hard, soft, or mixed mode. | | git_clean | Remove untracked files from the working tree with options for directories and force cleaning. |

Remote Operations

| Tool | Description | | ----------------- | -------------------------------------------------------------------------------------------- | | git_remote_add | Add a new remote repository with a name and URL. | | git_remote_list | List all configured remote repositories and their URLs. | | git_fetch | Fetch updates from a remote repository with options for specific branches. | | git_pull | Pull changes from a remote repository with options for rebase strategy. | | git_push | Push local changes to a remote repository with options for force push and upstream tracking. |

Advanced Operations

| Tool | Description | | ------------------ | ----------------------------------------------------------------------------------------- | | git_tag_create | Create a new tag with options for annotated tags with messages. | | git_tag_list | List all tags in the repository with their references. | | git_stash_create | Stash changes in the working directory with options for untracked files and descriptions. | | git_stash_list | List all stashes in the repository with their descriptions. | | git_stash_apply | Apply a stashed change without removing it from the stash list. | | git_stash_pop | Apply a stashed change and remove it from the stash list. | | git_cherry_pick | Apply changes from specific commits to the current branch. | | git_rebase | Rebase the current branch onto another branch with interactive mode options. | | git_log | Get commit history with customizable output format and depth. | | git_show | Show detailed information about a specific commit including diff changes. |

Resources

Git MCP Server exposes Git data through standard MCP resources:

Repository Resources

| Resource | Description | | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------- | | git://repo/{repoPath}/info | Basic Git repository information including current branch, status, and reference details | | git://repo/{repoPath}/branches | List of all branches in the repository with current branch indicator | | git://repo/{repoPath}/remotes | List of all configured remote repositories with their URLs | | git://repo/{repoPath}/tags | List of all tags in the repository with their references | | git://repo/{repoPath}/file/{filePath}?ref={ref} | Returns the content of a specific file at a given Git reference | | git://repo/{repoPath}/ls/{dirPath}?ref={ref} | Returns a list of files and directories at a specific path and reference | | git://repo/{repoPath}/diff/{fromRef}/{toRef}?path={path} | Returns a diff between two Git references (commits, branches, tags) | | git://repo/{repoPath}/diff-unstaged?path={path} | Returns a diff of all unstaged changes in the working directory | | git://repo/{repoPath}/diff-staged?path={path} | Returns a diff of all staged changes in the index | | git://repo/{repoPath}/log?maxCount={maxCount}&file={file} | Returns the commit history log with author, date, and message details | | git://repo/{repoPath}/blame/{filePath} | Returns line-by-line attribution showing which commit last modified each line | | git://repo/{repoPath}/commit/{commitHash} | Returns detailed information about a specific commit including diff changes |

Development

Build and Test

# Build the project
npm run build

# Watch for changes and rebuild automatically
npm run watch

# Test the server locally using the MCP inspector tool
npm run inspector

# Clean build artifacts
npm run clean

# Generate a file tree representation for documentation
npm run tree

# Clean and rebuild the project completely
npm run rebuild

License

Apache License 2.0 - See LICENSE for details.

<div align="center"> Built with the Model Context Protocol </div>

GIT MCP Server

GIT MCP Server

Table of Contents

Overview

Architecture & Components

Features

Resource Access

Git Operations

Installation

Prerequisites

Install from NPM

Install from Source

Usage

Running the Server

Integration with Claude

Integration with Other MCP Clients

Project Structure

Tools

Repository Operations

Branch Operations

Working Directory Operations

Remote Operations

Advanced Operations

Resources

Repository Resources

Development

Build and Test

License