Skip to main content
Glama
Git MCP Server

Git MCP Server

by yumeminami

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

Related MCP server: bgagents

🎯 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

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! 🚀

Available Tools

33 tools
close_issueC

Close an issue

Inputs: issue_id (required), platform (required), project_id (required). Returns: result

close_merge_requestA

Close a merge request without merging

Args: platform: The platform name (e.g., 'gitlab', 'github') project_id: The project identifier mr_id: The merge request/pull request ID **kwargs: Additional platform-specific parameters

Returns: Dict containing: - merge_request: Updated merge request details - message: Success message - platform: The platform name - project_id: The project identifier - mr_id: The merge request ID

Inputs: mr_id (required), kwargs (required), platform (required), project_id (required). Returns: result

close_milestoneC

Close a milestone

Inputs: platform (required), project_id (required), milestone_id (required). Returns: result

create_forkA

Create a fork of a repository

Args: platform: The platform name (github, gitlab) project_id: The repository ID to fork (owner/repo for GitHub, numeric for GitLab) **kwargs: Platform-specific fork parameters - GitHub: organization, name, default_branch_only - GitLab: namespace, name, path

Inputs: kwargs (required), platform (required), project_id (required). Returns: result

create_issueC

Create a new issue in a project

Inputs: title (required), kwargs (required), platform (required), project_id (required), +4 more. Returns: result

create_issue_commentC

Create a comment on an issue

Inputs: body (required), kwargs (required), issue_id (required), platform (required), +1 more. Returns: result

create_merge_requestA

Create a new merge request with cross-project support

Args: platform: Git platform name (github, gitlab, etc.) project_id: Source project ID (for cross-project MRs) or project ID (for same-project MRs) title: Merge request title source_branch: Source branch name or 'owner:branch' format for cross-repo target_branch: Target branch name (default: 'main') description: Optional merge request description assignee: Optional assignee username target_project_id: Optional target project ID for cross-project merge requests **kwargs: Additional platform-specific parameters

Returns: Dict containing merge request details

Examples: # Same-project MR create_merge_request("gitlab", "123", "Fix bug", "feature-branch", "main")

# Cross-project MR (fork to upstream)
create_merge_request("gitlab", "456", "Fix bug", "feature-branch", "main",
                   target_project_id="123")

# GitHub cross-repo PR (using branch format)
create_merge_request("github", "upstream/repo", "Fix bug", "fork-owner:feature-branch", "main")

Inputs: title (required), kwargs (required), platform (required), project_id (required), +6 more. Returns: result

create_milestoneC

Create a new milestone in a project. due_date format: YYYY-MM-DD

Inputs: title (required), platform (required), project_id (required), due_date, +1 more. Returns: result

create_projectC

Create a new project on the specified platform

Inputs: name (required), kwargs (required), platform (required). Returns: result

delete_projectC

Delete a project from the specified platform

Inputs: platform (required), project_id (required). Returns: result

get_current_user_infoC

Get current user information directly from platform API

Inputs: platform (required). Returns: result

get_fork_infoB

Get fork information for a repository

Args: platform: The platform name (github, gitlab) project_id: The repository ID to check

Returns: Dictionary with fork status, parent repository, and other fork details

Inputs: platform (required), project_id (required). Returns: result

get_issue_by_urlA

Get issue details by URL. Supports GitLab and GitHub URLs.

Example URLs:

Inputs: url (required). Returns: result

get_issue_detailsC

Get detailed information about a specific issue including comments

Inputs: issue_id (required), platform (required), project_id (required). Returns: result

get_merge_request_commitsC

Get commits for a merge request

Args: platform: The platform name (e.g., 'gitlab', 'github') project_id: The project identifier mr_id: The merge request/pull request ID **filters: Optional filters for commit selection

Returns: Dict containing: - mr_id: The merge request ID - total_commits: Number of commits - commits: List of commit details with sha, message, author, dates, etc.

Inputs: mr_id (required), filters (required), platform (required), project_id (required). Returns: result

get_merge_request_detailsB

Get detailed information about a specific merge request

Inputs: mr_id (required), platform (required), project_id (required). Returns: result

get_merge_request_diffA

Get diff/changes for a merge request

Args: platform: The platform name (e.g., 'gitlab', 'github') project_id: The project identifier mr_id: The merge request/pull request ID **options: Optional parameters: - format: Response format ('json', 'unified') - default: 'json' - include_diff: Include actual diff content (bool) - default: True

Returns: Dict containing: - mr_id: The merge request ID - total_changes: Summary of additions, deletions, files changed - files: List of changed files with details - diff_format: Format of the response - truncated: Whether response was truncated

Inputs: mr_id (required), options (required), platform (required), project_id (required). Returns: result

get_platform_configB

Get configuration information for a specific platform

Inputs: platform (required). Returns: result

get_project_detailsC

Get detailed information about a specific project

Inputs: platform (required), project_id (required). Returns: result

list_all_issuesC

List issues across all projects (global search). No project_id needed.

Inputs: filters (required), platform (required), limit, state. Returns: result

list_forksA

List forks of a repository

Args: platform: The platform name (github, gitlab) project_id: The repository ID to list forks for limit: Maximum number of forks to return

Returns: List of fork repositories

Inputs: platform (required), project_id (required), limit. Returns: result

list_issuesC

List issues in a project. State can be 'opened', 'closed', or 'all'

Inputs: filters (required), platform (required), project_id (required), limit, +1 more. Returns: result

list_merge_requestsC

List merge requests in a project. State can be 'opened', 'closed', 'merged', or 'all'

Inputs: filters (required), platform (required), project_id (required), limit, +1 more. Returns: result

list_milestonesB

List milestones for a project. State can be 'active', 'closed', or 'all'

Inputs: platform (required), project_id (required), state. Returns: result

list_my_issuesB

List issues assigned to me across all projects.

Inputs: filters (required), platform (required), limit, state. Returns: result

list_my_merge_requestsB

List merge requests created by the current user (automatically uses configured username)

Inputs: filters (required), platform (required), project_id (required), limit, +1 more. Returns: result

list_platformsA

List all configured Git platforms (GitLab, GitHub, etc.)

Inputs: no named parameters. Returns: result

list_projectsC

List projects from a specified Git platform

Inputs: filters (required), platform (required), limit. Returns: result

refresh_platform_usernameB

Refresh username for a configured platform by fetching from token

Inputs: platform (required). Returns: result

test_platform_connectionC

Test connection to a configured platform

Inputs: platform (required). Returns: result

update_issueC

Update an existing issue

Inputs: kwargs (required), issue_id (required), platform (required), project_id (required), +6 more. Returns: result

update_merge_requestB

Update a merge request (title, description, etc.)

Args: platform: The platform name (e.g., 'gitlab', 'github') project_id: The project identifier mr_id: The merge request/pull request ID **kwargs: Update parameters (title, description, state, etc.)

Returns: Dict containing: - merge_request: Updated merge request details - message: Success message - platform: The platform name - project_id: The project identifier - mr_id: The merge request ID

Inputs: mr_id (required), kwargs (required), platform (required), project_id (required). Returns: result

update_milestoneC

Update an existing milestone. due_date format: YYYY-MM-DD

Inputs: platform (required), project_id (required), milestone_id (required), state, +3 more. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3/5.0

    Scored across 33 tools

    Disambiguation5/5

    All tools have clearly distinct purposes; even multiple list tools for issues and merge requests are differentiated by scope (project-specific, global, user-specific). No overlapping functionality.

    Naming Consistency5/5

    Consistent verb_noun pattern using snake_case throughout (e.g., list_issues, create_milestone, get_fork_info). No mixing of conventions.

    Tool Count3/5

    33 tools is on the higher side but covers multiple platforms and domains (platform config, projects, issues, merge requests, milestones, forks). Slightly heavy but not excessive for the scope.

    Completeness3/5

    Major operations are covered but notable gaps exist: missing update_project, delete_issue, merge_merge_request (only close), delete_milestone. No search/code tools. Surface is functional but incomplete.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers