MCP 服务器

Git MCP Server

Enables local git operations including commit, branch, push, pull, status, and sync with conventional commit enforcement and branch naming conventions.

README

Git MCP Server

Python MCP (Model Context Protocol) server for local git operations, providing native tool integration with Claude Code and other MCP clients.

Features

6 Git Tools: Commit, branch, push, pull, status, and sync operations
Native MCP Integration: Works seamlessly with Claude Code
Conventional Commits: Enforced commit message format with type prefixes
Branch Naming: Enforced conventions (issue-N-description, feature-*, etc.)
Token Authentication: Automatic GitHub token injection for remote operations

Installation

From PyPI

pip install git-mcp-server
# or with uv
uvx git-mcp-server

From Source

git clone https://github.com/rriesco/git-mcp-server.git
cd git-mcp-server
uv sync

Configuration

Environment Variables

Variable	Required	Description
`GITHUB_TOKEN`	For push/pull	GitHub Personal Access Token for authenticated git operations

Claude Code Configuration

Add to your MCP configuration (~/.config/claude-code/mcp-config.json):

{
  "mcpServers": {
    "git-manager": {
      "type": "stdio",
      "command": "uvx",
      "args": ["git-mcp-server"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

Available Tools

Tool	Description
`git_create_branch`	Create and checkout a new branch with naming conventions
`git_commit`	Create conventional commit with Claude attribution
`git_push`	Push commits to remote with upstream tracking
`git_pull`	Pull commits from remote
`git_status`	Get current branch, tracking info, and file changes
`git_sync_with_main`	Sync current branch with main (merge or rebase)

Usage Examples

Create a Branch

result = git_create_branch(
    issue_number=42,
    description="add-feature-x"
)
# Creates: issue-42-add-feature-x

Commit Changes

result = git_commit(
    type="feat",
    message="implement user authentication"
)
# Creates: feat: implement user authentication
#
# Co-Authored-By: Claude <noreply@anthropic.com>

Check Status

result = git_status()
# Returns: {branch, tracking, ahead, behind, staged, modified, untracked, clean}

Sync with Main

result = git_sync_with_main(
    main_branch="main",
    strategy="merge"  # or "rebase"
)

Commit Types

The git_commit tool enforces conventional commit types:

Type	Description
`feat`	New feature
`fix`	Bug fix
`docs`	Documentation only
`style`	Code style (formatting, semicolons, etc.)
`refactor`	Code refactoring
`perf`	Performance improvement
`test`	Adding or fixing tests
`build`	Build system or dependencies
`ci`	CI/CD configuration
`chore`	Maintenance tasks
`revert`	Revert previous commit

Branch Naming

The git_create_branch tool enforces naming conventions:

issue-<N>-<description> - For GitHub issues
feature-<description> - For features without issues
fix-<description> - For bug fixes
refactor-<description> - For refactoring

Development

Prerequisites

Python >= 3.10
uv (recommended) or pip
Git

Setup

git clone https://github.com/rriesco/git-mcp-server.git
cd git-mcp-server
uv sync

Running Tests

# Unit tests only (fast)
uv run pytest -m "not integration" -v

# Integration tests (creates real git repos in temp directories)
uv run pytest -m integration -v

# All tests with coverage
uv run pytest --cov=git_mcp_server --cov-report=term-missing

Type Checking

uv run mypy src/git_mcp_server --strict

Architecture

Claude Code / MCP Client
      |
      | MCP Protocol (stdio)
      v
┌─────────────────────────────┐
│  Python FastMCP Server      │
│  - Tool Registry            │
│  - GitPython Client         │
│  - Error Handling           │
│  - Type Validation          │
└─────────────┬───────────────┘
              |
              | GitPython
              v
        Local Git Repo

Project Structure

git-mcp-server/
├── src/git_mcp_server/
│   ├── server.py              # Server entry point
│   ├── tools/
│   │   ├── branch.py          # Branch operations
│   │   ├── commit.py          # Commit operations
│   │   ├── remote.py          # Push/pull operations
│   │   ├── status.py          # Status queries
│   │   └── sync.py            # Sync with main
│   └── utils/
│       ├── git_client.py      # Singleton Repo instance
│       └── errors.py          # Structured error handling
└── tests/
    ├── test_*.py              # Unit tests
    └── integration/           # Integration tests