Git MCP Server
Allows interaction with GitHub repositories, issues, and pull requests, enabling complete issue-to-code workflows including issue analysis, planning, implementation, testing, documentation, and PR creation.
Provides tools for managing GitLab repositories, issues, and merge requests, supporting issue-to-code automation with slash commands for analysis, planning, implementation, testing, documentation, and merge request creation.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Git MCP Server /issue https://github.com/user/repo/issues/42"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 123That'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-claudeFor Gemini CLI:
# Install from PyPI
uv tool install git_mcp_server
# Setup Gemini CLI integration (adds MCP server + slash commands)
git-mcp-server --install-geminiFor Codex:
# Install from PyPI
uv tool install git_mcp_server
# Setup Codex integration (adds MCP server + slash commands)
git-mcp-server --install-codexThis 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-githubThe 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 platformstest_platform_connection(platform)- Test platform connectivityget_platform_config(platform)- Get platform configurationrefresh_platform_username(platform)- Update username from token
Issue Operations
list_my_issues(platform)- List issues assigned to youget_issue_by_url(url)- Analyze issues from GitLab/GitHub URLsget_issue_details(platform, project_id, issue_id)- Get detailed issue infocreate_issue(platform, project_id, title, ...)- Create new issues
Project Management
list_projects(platform)- List accessible projectsget_project_details(platform, project_id)- Get project information
Merge Requests
list_merge_requests(platform, project_id)- List merge requestscreate_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-gitlabSecurity 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.pyMCP 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.jsonin project
Gemini CLI:
Global settings: Configured in
~/.gemini/settings.jsonProject 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.tomlCommands: Located in
~/.codex/prompts/directoryMemory 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 456Bug 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-serverCommon 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_serverSlash 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-codexUpdate 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-gitlabMCP Server:
# Start MCP server with debug logging
git-mcp-server --debug
# Shows detailed MCP tool calls and responses
git-mcp-server --debugEnvironment 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-serverLog 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 --debugLog 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 platformsRich 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 githubDebug 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 statusLog 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):
CLI flags:
--debugoverrides environment variablesEnvironment variables:
GIT_MCP_SERVER_*settingsDefault 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' successfulDebugging 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 projectsFile + 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-serverThis 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-codexThen try /issue in your AI assistant! 🚀
Available Tools
33 toolsclose_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
Scored across 33 tools
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.
Consistent verb_noun pattern using snake_case throughout (e.g., list_issues, create_milestone, get_fork_info). No mixing of conventions.
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.
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
Related MCP Connectors
GitHub Copilot MCP: code, repo, PR, workflow tools for AI assistants.
Connect AI assistants to GitHub - manage repos, issues, PRs, and workflows through natural language.
AI-native git hosting — repos, PRs, issues, CI gates, and AI code review over MCP (60 tools).
Use AI models for chat, image, and video generation from Claude Code and other MCP hosts.
Related MCP Servers
- AlicenseBqualityDmaintenanceIntegrates GitHub Copilot with MCP-compatible tools to provide AI-powered code assistance, including chat, code explanation, and reviews. It leverages existing GitHub CLI authentication to support multiple models like GPT-4o and Claude 3.5 Sonnet.432 npm2MIT
- AlicenseNot gradedqualityDmaintenanceEnables turning AI code agents like Anthropic Claude and OpenAI Codex into background agents accessible via MCP protocol for code generation, branch creation, and PR automation.50MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI-powered GitHub interactions including repository analysis, code search, PR reviews, and more through the MCP protocol.4MIT
- AlicenseNot gradedqualityAmaintenanceEnables AI coding agents and teams to turn GitHub Projects v2 into an autonomous task substrate for registering, claiming, tracking, reviewing, and completing work, while also supporting AI-powered PRD generation, sprint planning, issue triage, roadmap creation, GitHub Actions/releases/branches, and MCP resources/prompts.272 npmMIT