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, leveraging the simple-git library for core functionality 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 (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

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

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