rriesco-mcp-git 0.1.2

MCP server for local git operations - commit, branch, push, pull, sync

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 <[e-mail]>

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

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