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

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

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:

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

License

MIT License - see LICENSE for details.

Contributing

Contributions are welcome! Please read the contributing guidelines before submitting PRs.

1. Fork the repository
2. Create a feature branch
3. Make your changes with tests
4. Submit a pull request

Links

• MCP Protocol Documentation
• GitPython Documentation
• FastMCP Framework