Git MCP Server

A Model Context Protocol (MCP) server for Claude Code, Gemini CLI, and Codex that enables complete issue-to-code automation across GitHub and GitLab platforms.

🚀 What is Git MCP Server?

Git MCP Server transforms your development workflow by connecting AI assistants directly to your Git repositories. It provides:

• 🤖 MCP Integration: Full support for Claude Code, Gemini CLI, and Codex via Model Context Protocol
• 📋 Issue-to-Code Workflow: Complete automation from issue analysis to PR creation
• 🎯 Slash Commands: Pre-built workflow commands (/issue, /plan, /implement, /test, /doc, /pr)
• 🔧 Multi-Platform: Unified interface for GitLab and GitHub
• 🔐 Secure: Keyring-based token storage with auto-username detection

🎯 Issue-to-Code Workflow

Transform how you handle development tasks with these automated slash commands:

# 1. Analyze any issue from URL
/issue https://gitlab.com/group/project/-/issues/123

# 2. Generate development plan
/plan

# 3. Implement the solution
/implement

# 4. Create comprehensive tests
/test

# 5. Update documentation
/doc

# 6. Create PR/MR and close issue
/pr 123

That's it! From issue analysis to pull request in 6 commands.

📦 Installation

Quick Setup (Recommended)

For Claude Code:

# Install from PyPI
uv tool install git_mcp_server

# Setup Claude Code integration (adds MCP server + slash commands)
git-mcp-server --install-claude

For Gemini CLI:

# Install from PyPI
uv tool install git_mcp_server

# Setup Gemini CLI integration (adds MCP server + slash commands)
git-mcp-server --install-gemini

For Codex:

# Install from PyPI
uv tool install git_mcp_server

# Setup Codex integration (adds MCP server + slash commands)
git-mcp-server --install-codex

This automatically:

• ✅ Installs Git MCP Server globally
• ✅ Configures MCP server in Claude Code/Gemini CLI/Codex
• ✅ Installs slash commands to respective directories
• ✅ Adds code memory guidelines (Codex: AGENTS.md)
• ✅ Provides setup instructions

Alternative Installation

# Using pip
pip install git_mcp_server
git-mcp-server --install-claude  # or --install-gemini or --install-codex

# From source (development)
git clone <repository-url>
cd git_mcp
uv tool install --from . git_mcp_server
git-mcp-server --install-claude  # or --install-gemini or --install-codex

⚡ Quick Start

1. Configure Your Git Platform

# Add GitLab (public or private instance)
git-mcp config add my-gitlab gitlab --url https://gitlab.com

# Add GitHub (public or GitHub Enterprise)
git-mcp config add my-github github --url https://github.com

# Test the connections
git-mcp config test my-gitlab
git-mcp config test my-github

The system will automatically:

• 🔐 Prompt for your access token
• 👤 Fetch your username automatically
• 💾 Store credentials securely in system keyring

2. Start Using Slash Commands

In Claude Code, Gemini CLI, or Codex, you can now use:

/issue - Smart Issue Analysis

# List your assigned issues
/issue

# Analyze specific issue from any GitLab/GitHub URL
/issue https://gitlab.com/group/project/-/issues/123

/plan - Generate Development Plans

# Create structured implementation plan based on issue analysis
/plan

/implement - Code Implementation

# Implement the planned solution with best practices
/implement

/test - Test Generation

# Generate comprehensive test suites
/test

/doc - Documentation Updates

# Update documentation and API docs
/doc

/pr - Create Pull Requests

# Create PR/MR and automatically close related issue
/pr 123

🛠️ Available MCP Tools

When configured, Claude Code, Gemini CLI, and Codex gain access to these powerful tools:

Platform Management

• list_platforms() - List configured Git platforms
• test_platform_connection(platform) - Test platform connectivity
• get_platform_config(platform) - Get platform configuration
• refresh_platform_username(platform) - Update username from token

Issue Operations

• list_my_issues(platform) - List issues assigned to you
• get_issue_by_url(url) - Analyze issues from GitLab/GitHub URLs
• get_issue_details(platform, project_id, issue_id) - Get detailed issue info
• create_issue(platform, project_id, title, ...) - Create new issues

Project Management

• list_projects(platform) - List accessible projects
• get_project_details(platform, project_id) - Get project information

Merge Requests

• list_merge_requests(platform, project_id) - List merge requests
• create_merge_request(platform, project_id, ...) - Create pull/merge requests

🎛️ Configuration

Platform Configuration

Git MCP Server stores configuration in ~/.git-mcp/config.yaml:

platforms:
  my-gitlab:
    type: gitlab
    url: https://gitlab.com
    username: myuser  # Auto-fetched from token

  company-gitlab:
    type: gitlab
    url: https://git.company.com
    username: myuser

defaults:
  platform: my-gitlab

Security Note: Access tokens are stored securely in your system keyring, not in config files.

Automatic Username Detection

# Username automatically fetched from token
git-mcp config add my-gitlab gitlab --url https://gitlab.com

# Refresh username for existing platforms
git-mcp config refresh-username my-gitlab

🔧 Advanced Usage

Running MCP Server Directly

# Start MCP server (for debugging)
git-mcp-server

# Interactive development mode
uv run mcp dev git_mcp/mcp_server.py

MCP Scope Configuration

Claude Code:

• User scope (recommended): Available across all Claude Code projects
• Local scope: Only in current project directory
• Project scope: Shared via .mcp.json in project

Gemini CLI:

• Global settings: Configured in ~/.gemini/settings.json
• Project settings: Can override in project-specific settings
• Commands: Located in ~/.gemini/commands/ (global) or .gemini/commands/ (project)

Codex:

• Global configuration: MCP server configured in ~/.codex/config.toml
• Commands: Located in ~/.codex/prompts/ directory
• Memory integration: Code guidelines in ~/.codex/AGENTS.md

Development Setup

# Clone repository
git clone <repository-url>
cd git_mcp

# Install in development mode
uv sync --all-extras

# Run locally
uv run git-mcp-server

# Install development version globally
uv tool install --from . git_mcp_server --force

📚 Workflow Examples

Complete Feature Development

# Start with your assigned issues
/issue

# Select and analyze specific issue
/issue https://gitlab.com/team/project/-/issues/456

# Generate implementation plan
/plan

# Implement with best practices
/implement

# Create comprehensive tests
/test

# Update documentation
/doc

# Create PR and close issue
/pr 456

Bug Fix Workflow

# Analyze bug report
/issue https://gitlab.com/team/project/-/issues/789

# Plan the fix
/plan

# Implement fix
/implement

# Add regression tests
/test

# Update docs if needed
/doc

# Submit fix
/pr 789

🔍 Troubleshooting

Verify Installation

# Check global installation
which git-mcp-server
git-mcp-server --help

# Verify Claude Code integration
claude mcp list

# Verify Gemini CLI integration
gemini /mcp

# Verify Codex integration
ls ~/.codex/prompts/  # Should show slash commands
cat ~/.codex/config.toml  # Should show git-mcp-server

# Test MCP connection
echo '{"jsonrpc": "2.0", "method": "initialize", "params": {"protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": {"name": "test", "version": "1.0.0"}}, "id": 1}' | git-mcp-server

Common Issues

"No MCP servers configured"

# Reinstall MCP integration
git-mcp-server --install-claude  # or --install-gemini

"Command not found" after installation

# Reinstall with uv
uv tool uninstall git_mcp_server
uv tool install git_mcp_server

Slash commands not working

# Check commands directory (Claude Code)
ls ~/.claude/commands/

# Check commands directory (Gemini CLI)
ls ~/.gemini/commands/

# Check commands directory (Codex)
ls ~/.codex/prompts/

# Reinstall if missing
git-mcp-server --install-claude  # or --install-gemini or --install-codex

Update to Latest Version

# Update package
uv tool install git_mcp_server --upgrade

# Reinstall integration
git-mcp-server --install-claude  # or --install-gemini

🐛 Debug & Logging

Git MCP Server includes comprehensive debugging and logging capabilities to help troubleshoot issues and understand system behavior.

Debug Mode

Enable debug mode to get detailed logging output with enhanced formatting:

CLI Commands:

# Enable debug mode for CLI commands
git-mcp --debug config list
git-mcp --debug issue list --platform github

# Debug mode shows detailed operation logs
git-mcp --debug config test my-gitlab

MCP Server:

# Start MCP server with debug logging
git-mcp-server --debug

# Shows detailed MCP tool calls and responses
git-mcp-server --debug

Environment Variables

Configure logging behavior using environment variables:

# Set log level (DEBUG, INFO, WARNING, ERROR)
export GIT_MCP_SERVER_LOG_LEVEL=DEBUG

# Enable debug mode (alternative to --debug flag)
export GIT_MCP_SERVER_DEBUG=true

# Log to file instead of/in addition to console
export GIT_MCP_SERVER_LOG_FILE=~/.git-mcp/debug.log

# Run with environment variables
git-mcp-server

Log File Configuration

Enable file logging for persistent debugging:

# Set log file path
export GIT_MCP_SERVER_LOG_FILE=~/.git-mcp/git-mcp.log

# Logs will be appended to file with timestamps
git-mcp-server --debug

Log file format:

2025-08-15 02:05:23,123 - git_mcp.mcp_server - DEBUG - MCP Tool: list_platforms called
2025-08-15 02:05:23,124 - git_mcp.platforms.gitlab - DEBUG - Connecting to GitLab at https://gitlab.com
2025-08-15 02:05:23,156 - git_mcp.mcp_server - DEBUG - MCP Tool: list_platforms returned 2 platforms

Rich Console Output

Debug mode enables rich console formatting with:

• 🎨 Colored output for different log levels
• 📁 File paths shown for debug messages
• ⏰ Timestamps for all debug entries
• 📊 Structured tracebacks for errors
• 🔍 Local variables in error traces (debug mode only)

Troubleshooting Common Issues

Enable debug mode when experiencing:

# Connection issues
export GIT_MCP_SERVER_LOG_LEVEL=DEBUG
git-mcp config test my-gitlab

# MCP tool failures
git-mcp-server --debug

# Authentication problems
export GIT_MCP_SERVER_DEBUG=true
git-mcp issue list --platform github

Debug MCP Integration:

# Test MCP server communication
echo '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}' | git-mcp-server --debug

# Claude Code MCP debugging
claude mcp logs git-mcp-server

# Check MCP server status
claude mcp status

Log Levels Explained

• DEBUG: Detailed function calls, API requests, internal operations
• INFO: General information about operations and status
• WARNING: Non-critical issues that may need attention
• ERROR: Critical errors that prevent operation

Environment Variable Priority

Configuration priority (highest to lowest):

1. CLI flags: --debug overrides environment variables
2. Environment variables: GIT_MCP_SERVER_* settings
3. Default values: INFO level, console output only

Debug Examples

Debugging Platform Connection:

# Enable debug and test connection
export GIT_MCP_SERVER_LOG_LEVEL=DEBUG
git-mcp config test my-gitlab

# Output shows detailed connection process:
# DEBUG - Connecting to GitLab at https://gitlab.com
# DEBUG - Authentication successful for user: myusername
# DEBUG - API version: v4
# INFO - Connection to 'my-gitlab' successful

Debugging MCP Tool Calls:

# Start server with debug logging
git-mcp-server --debug

# Shows MCP tool invocations:
# DEBUG - MCP Tool: list_projects called with platform='gitlab'
# DEBUG - Found 15 projects for user
# DEBUG - MCP Tool: list_projects returned 15 projects

File + Console Logging:

# Log to both console and file
export GIT_MCP_SERVER_LOG_LEVEL=DEBUG
export GIT_MCP_SERVER_LOG_FILE=~/.git-mcp/debug.log

# Console shows rich formatted output
# File contains timestamped plain text logs
git-mcp-server

This logging system helps diagnose issues, understand system behavior, and provides detailed insights for development and troubleshooting.

🌟 Key Benefits

• ⚡ Speed: From issue to PR in minutes, not hours
• 🎯 Focus: AI handles boilerplate, you focus on logic
• 📋 Consistency: Standardized workflow across all projects
• 🔧 Flexibility: Works with any GitLab instance
• 🤖 Intelligence: AI assistants understand your codebase context
• 🔐 Security: Secure credential management

🛣️ Supported Platforms

• ✅ GitLab - Full support (gitlab.com and private instances)
• ✅ GitHub - Full support (github.com and GitHub Enterprise)

🤝 Contributing

Issues and Pull Requests welcome! This project enables powerful AI-assisted development workflows.

📄 License

MIT License

---

Ready to supercharge your development workflow?

# For Claude Code
uv tool install git_mcp_server && git-mcp-server --install-claude

# For Gemini CLI
uv tool install git_mcp_server && git-mcp-server --install-gemini

# For Codex
uv tool install git_mcp_server && git-mcp-server --install-codex

Then try /issue in your AI assistant! 🚀