https://github.com/cyanheads/git-mcp-server
A Model Context Protocol (MCP) server to provide git tools for LLM Agents
https://github.com/cyanheads/git-mcp-server
ai git llm mcp modelcontextprotocol
Last synced: 3 months ago
JSON representation
A Model Context Protocol (MCP) server to provide git tools for LLM Agents
- Host: GitHub
- URL: https://github.com/cyanheads/git-mcp-server
- Owner: cyanheads
- License: apache-2.0
- Created: 2024-12-16T12:21:40.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2025-03-15T04:47:52.000Z (3 months ago)
- Last Synced: 2025-03-15T05:19:11.453Z (3 months ago)
- Topics: ai, git, llm, mcp, modelcontextprotocol
- Language: TypeScript
- Homepage:
- Size: 51.8 KB
- Stars: 9
- Watchers: 1
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- mcp-index - Git MCP Server - Interact with Git repositories through a robust API, enabling operations such as cloning, committing, pushing, and repository management. Focuses on optimizing performance, error handling, and secure command execution. (Developer Tools)
- awesome - cyanheads/git-mcp-server - An MCP (Model Context Protocol) server enabling LLMs and AI agents to interact with Git repositories. Provides tools for comprehensive Git operations including clone, commit, branch, diff, log, status, push, pull, merge, rebase, worktree, tag management, and more, via the MCP standard. STDIO & HTTP. (TypeScript)
README
# GIT MCP Server
[](https://www.typescriptlang.org/)
[](https://modelcontextprotocol.io/)
[]()
[](https://opensource.org/licenses/Apache-2.0)
[]()
[](https://github.com/cyanheads/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](#overview)
- [Architecture & Components](#architecture--components)
- [Features](#features)
- [Resource Access](#resource-access)
- [Git Operations](#git-operations)
- [Installation](#installation)
- [Prerequisites](#prerequisites)
- [Install from NPM](#install-from-npm)
- [Install from Source](#install-from-source)
- [Usage](#usage)
- [Running the Server](#running-the-server)
- [Integration with Claude](#integration-with-claude)
- [Integration with Other MCP Clients](#integration-with-other-mcp-clients)
- [Project Structure](#project-structure)
- [Tools](#tools)
- [Repository Operations](#repository-operations)
- [Branch Operations](#branch-operations)
- [Working Directory Operations](#working-directory-operations)
- [Remote Operations](#remote-operations)
- [Advanced Operations](#advanced-operations)
- [Resources](#resources)
- [Repository Resources](#repository-resources)
- [Development](#development)
- [Build and Test](#build-and-test)
- [License](#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:
Click to expand Mermaid diagram
```mermaid
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
```bash
npm install -g git-mcp-server
```
### Install from Source
```bash
git clone https://github.com/cyanheads/git-mcp-server.git
cd git-mcp-server
npm install
npm run build
```
## Usage
### Running the Server
```bash
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:
```json
{
"mcpServers": {
"git": {
"command": "git-mcp-server",
"args": [],
"env": {},
"disabled": false
}
}
}
```
### Integration with Other MCP Clients
Use the MCP inspector to test the server:
```bash
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
| 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
```bash
# 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](LICENSE) for details.
---
Built with the Model Context Protocol