📌Overview

Purpose: The Git MCP Server facilitates interactions with Git repositories through a standardized Model Context Protocol (MCP) interface, enabling secure management of repositories without direct filesystem or command-line access.

Overview: This server acts as an abstraction layer over Git operations, providing a set of tools to manage repositories, branches, commits, and files in a consistent manner. By adhering to MCP standards, it ensures ease of integration with various AI assistants and LLM agents.

Key Features:

• Repository Management: Initialize and manage repositories with operations like cloning and checking status to streamline repository handling during development.

• Branch Operations: Create, delete, and merge branches effortlessly, enhancing the flexibility of workflow management within Git.

• Working Directory Operations: Stage changes, commit updates, and retrieve diffs, allowing effective tracking of modifications and enhancements made to files.

• Remote Operations: Manage remote repositories with capabilities to add, fetch, pull, and push changes, facilitating collaborative development efforts.

• Advanced Git Commands: Execute intricate operations such as managing tags, stashing changes, and rebasing, providing developers with sophisticated tools for version control.

---

GIT MCP Server

A Model Context Protocol (MCP) server providing tools for interacting with Git repositories. It allows AI assistants and LLM agents to manage repositories, branches, commits, and files via a standardized interface without direct filesystem or command-line access. The server exposes Git operations as MCP resources and tools, using the simple-git library and maintaining 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 consists of several layers: API Layer (MCP Protocol, Validation), Core Services (Git Service using simple-git, Error Service), Resource Layer (Repository, Diff, File, History resources), and Tool Layer (Repository Tools, Branch Tools, Working Directory Tools, Remote Tools, Advanced Tools).

Core components:

• MCP Server (server.ts): Creates a server exposing resources and tools via the MCP SDK.
• Git Service (services/git-service.ts): Abstraction over simple-git for Git operations.
• Resources (resources/): Expose Git data (status, logs, file content) as MCP resources.
• Tools (tools/): Expose Git actions (commit, push, pull) as MCP tools with validated inputs.
• Error Handling (services/error-service.ts): Standard error reporting for Git and MCP operations.
• Entry Point (index.ts): Initializes and starts the server using standard I/O transport.

Features

Resource Access

Expose Git repository information through MCP resources:

• Access repository info: current branch, status, references
• List branches, remotes, tags
• Access file content and directory listings at specific refs
• View diffs between references, and staged/unstaged changes
• View commit history and file blame
• Access detailed commit information

Git Operations

Execute Git commands via MCP tools:

• Initialize, clone, check repository status
• Manage branches: create, list, checkout, delete, merge
• Work with working directory: stage, unstage, commit, diff
• Manage remotes: add, list, fetch, pull, push
• Advanced operations: manage tags, stash, cherry-pick, rebase, 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:

git-mcp-server

If running from source:

node build/index.js

The server communicates via stdin/stdout using the Model Context Protocol and works with any MCP client.

Integration with Claude

Add the following snippet to your Claude configuration file (e.g., cline_mcp_settings.json):

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

Integration with Other MCP Clients

Test the server using the MCP inspector:

npx @modelcontextprotocol/inspector git-mcp-server

Or if running from source:

npx @modelcontextprotocol/inspector build/index.js

Project Structure

git-mcp-server/
├── src/
│   ├── index.ts           # Entry point
│   ├── server.ts          # MCP server implementation
│   ├── resources/         # MCP Resource implementations
│   ├── services/          # Core logic and integrations
│   ├── tools/             # MCP Tool implementations
│   ├── types/             # TypeScript type definitions
│   └── utils/             # Utility functions
├── build/                 # Compiled JavaScript output
├── docs/                  # Documentation
├── logs/                  # Log files
├── scripts/               # Development helper scripts
├── .env.example           # Environment variables example
├── .gitignore             # Git ignore rules
├── LICENSE                # License file
├── package.json           # Metadata and dependencies
├── package-lock.json      # Dependency lock
├── README.md              # This file
└── tsconfig.json          # TypeScript compiler config

Tools

Repository Operations

Tool	Description
git_init	Initialize a new Git repository at the specified path (supports bare repo).
git_clone	Clone a Git repository from a remote URL with branch and depth options.
git_status	Get the status of the repository, including working directory and staging.

Branch Operations

Tool	Description
git_branch_list	List all branches with option to include remotes.
git_branch_create	Create a new branch with optional checkout.
git_checkout	Checkout a branch, tag, or commit; create branch option available.
git_branch_delete	Delete a branch, force deletion supported.
git_merge	Merge a branch with customizable message and strategy.

Working Directory Operations

Tool	Description
git_add	Stage files or directories.
git_reset	Unstage files or all staged changes.
git_commit	Commit staged changes with message, author, and amend options.
git_diff_unstaged	Get diff of unstaged changes; supports specific files.
git_diff_staged	Get diff of staged changes; supports specific files.
git_reset_commit	Reset repository to a specific ref with mode options (hard, soft, mixed).
git_clean	Remove untracked files, supports directories and force options.

Remote Operations

Tool	Description
git_remote_add	Add a new remote repository with name and URL.
git_remote_list	List configured remotes and URLs.
git_fetch	Fetch updates from remote with branch options.
git_pull	Pull changes from remote with rebase strategy option.
git_push	Push changes to remote with force and upstream tracking options.

Advanced Operations

Tool	Description
git_tag_create	Create a new tag; supports annotated tags with messages.
git_tag_list	List all tags with references.
git_stash_create	Stash changes with untracked files and description options.
git_stash_list	List all stashes with descriptions.
git_stash_apply	Apply a stash without removing it.
git_stash_pop	Apply and remove a stash.
git_cherry_pick	Apply changes from specific commits.
git_rebase	Rebase current branch onto another; supports interactive mode.
git_log	Get commit history with customizable format and depth.
git_show	Show detailed commit info including diffs.

Resources

Git MCP Server exposes Git data as MCP resources:

Resource	Description
git://repo/{repoPath}/info	Repository information: current branch, status, references
git://repo/{repoPath}/branches	List of all branches with current branch indicator
git://repo/{repoPath}/remotes	List of remotes with URLs
git://repo/{repoPath}/tags	List of tags with references
git://repo/{repoPath}/file/{filePath}?ref={ref}	File content at a given reference
git://repo/{repoPath}/ls/{dirPath}?ref={ref}	List files and directories at a path and reference
git://repo/{repoPath}/diff/{fromRef}/{toRef}?path={path}	Diff between two Git references
git://repo/{repoPath}/diff-unstaged?path={path}	Diff of unstaged changes
git://repo/{repoPath}/diff-staged?path={path}	Diff of staged changes
git://repo/{repoPath}/log?maxCount={maxCount}&file={file}	Commit history log
git://repo/{repoPath}/blame/{filePath}	Line-by-line last modification attribution
git://repo/{repoPath}/commit/{commitHash}	Detailed commit info including diffs

Development

Build and Test

npm run build       # Build the project
npm run watch       # Watch files and rebuild automatically
npm run inspector   # Test server with MCP inspector
npm run clean       # Clean build artifacts
npm run tree        # Generate file tree for docs
npm run rebuild     # Clean and rebuild project

License

Apache License 2.0 - See LICENSE for details.

---