GIT MCP Server

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 while maintaining proper security boundaries.

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

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:

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

        MCP --> Val
    end

    subgraph Core["Core Services"]
        direction LR
        GitService["Git Service"]
        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

Core Components:

• MCP Server: Uses the Model Context Protocol SDK to create a server that exposes resources and tools
• Git Service: Abstraction layer over simple-git to provide clean interfaces for Git operations
• Resources: Expose Git data through MCP resources with consistent URI templates
• Tools: Expose Git operations through MCP tools with well-defined schemas
• Error Handling: Standardized error handling and reporting

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

git-mcp-server

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:

{
  "mcpServers": {
    "git": {
      "command": "git-mcp-server",
      "args": [],
      "env": {},
      "disabled": false
    }
  }
}

Integration with Other MCP Clients

Use the MCP inspector to test the server:

npx @modelcontextprotocol/inspector git-mcp-server

Project Structure

The codebase follows a modular structure:

git-mcp-server/
├── src/
│   ├── index.ts           # Entry point
│   ├── server.ts          # MCP server implementation
│   ├── resources/         # Resource implementations
│   │   ├── descriptors.ts # Resource URI templates
│   │   ├── diff.ts        # Diff-related resources
│   │   ├── file.ts        # File-related resources
│   │   ├── history.ts     # History-related resources
│   │   ├── index.ts       # Resource registration
│   │   └── repository.ts  # Repository resources
│   ├── services/          # Service implementations
│   │   ├── error-service.ts # Error handling
│   │   └── git-service.ts   # Git operations abstraction
│   ├── tools/             # Tool implementations
│   │   ├── advanced.ts    # Advanced Git operations
│   │   ├── branch.ts      # Branch operations
│   │   ├── index.ts       # Tool registration
│   │   ├── remote.ts      # Remote operations
│   │   ├── repository.ts  # Repository operations
│   │   └── workdir.ts     # Working directory operations
│   ├── types/             # Type definitions
│   │   └── git.ts         # Git-related types
│   └── utils/             # Utility functions
│       └── validation.ts  # Input validation
└── scripts/               # Development scripts

Tools

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

Repository Operations

Branch Operations

Working Directory Operations

Remote Operations

Advanced Operations

Resources

Git MCP Server exposes Git data through standard MCP resources:

Repository Resources

Development

Build and Test

# Build the project
npm run build

# Watch for changes
npm run watch

# Test with MCP inspector
npm run inspector

# Clean build artifacts
npm run clean

# Rebuild completely
npm run rebuild

License

Apache License 2.0 - See LICENSE for details.