python-gitlab-mcp 1.0.0

Production-ready Model Context Protocol server for GitLab - 87 tools, 14 prompts, 13 resources

GitLab MCP Server

A production-ready Model Context Protocol (MCP) server that enables AI assistants like Claude Code to interact seamlessly with self-hosted GitLab instances.

Overview

The GitLab MCP Server provides a complete, type-safe interface for AI assistants to interact with GitLab, supporting:

• Repository Operations: Search code, browse files, manage branches and commits
• Issue Management: Create, update, close issues, manage labels and comments
• Merge Requests: Complete MR workflows including creation, review, approval, and merging
• CI/CD Pipelines: Monitor pipeline status, trigger jobs, access artifacts and logs
• Project Management: Milestones, labels, project settings
• Security & Compliance: Security scanning results, vulnerability tracking
• Advanced Features: Wikis, snippets, releases, user/group management

Built with strict Test-Driven Development (TDD) practices, featuring 1257 tests and 84% code coverage.

Transport Modes: stdio (default) and Streamable HTTP for remote clients Slim Mode: 3 meta-tools for 95% context reduction in LLM conversations

Features

Complete Tool Suite (87 Tools + 14 Prompts + 13 Resources)

Repository Tools (16)

• Search repositories, code, and commits
• Browse files and directory trees
• Create, update, delete files
• Manage branches and tags
• View commit history and diffs
• Compare branches

Issue Tools (8)

• Create, read, update, close issues
• Reopen closed issues
• Add comments and list comments
• Search and filter issues

Merge Request Tools (14)

• Create and manage merge requests
• Review code and add comments
• Approve and merge MRs
• Manage reviewers and assignees
• Track MR pipelines and changes

CI/CD Pipeline Tools (14)

• List and monitor pipelines
• Create, retry, cancel, delete pipelines
• View job logs and status
• Download and manage artifacts
• Retry and cancel jobs
• Play manual jobs

Project Management Tools (10)

• Create, search, and manage projects
• View project statistics
• Manage milestones
• Handle project members

Labels, Wikis, Snippets, Releases (19)

• Label management (4 tools)
• Wiki page operations (5 tools)
• Code snippets (5 tools)
• Release management (5 tools)

Users & Groups (6)

• User lookup and search
• Group listing and details
• Group member management

Meta Tools (3) - Slim Mode

• discover_tools - List available tools by category
• get_tool_schema - Get JSON schema for any tool
• execute_tool - Execute any tool dynamically

🔒 Security First

• Personal Access Token (PAT) authentication
• Environment-based credential management
• SSL/TLS verification with custom certificate support
• Secure credential storage using .env files (gitignored)
• Token scope validation and error handling

🚀 Performance Optimized

• Async/await throughout for non-blocking operations
• Efficient pagination for large datasets
• Configurable timeouts and retry logic
• Connection pooling via httpx
• Smart rate limiting awareness

Thoroughly Tested

• 1257 tests passing (100% pass rate)
• 84% code coverage (exceeds 80% requirement)
• Unit tests with mocked dependencies
• Integration tests with real GitLab API
• E2E tests validating full MCP protocol
• Type-safe with mypy validation

Quick Start

Prerequisites

• Python 3.10+
• GitLab instance (self-hosted CE/EE v15.0+ or GitLab.com)
• GitLab Personal Access Token with appropriate scopes

Installation

# Install from PyPI
pip install python-gitlab-mcp

# Or install from source
git clone https://github.com/wadew/gitlab-mcp.git
cd gitlab-mcp
pip install -e ".[dev]"

Configuration

1. Create Personal Access Token

Create a GitLab Personal Access Token with these scopes:

• api - Full API access
• read_repository - Read repository content
• write_repository - Write repository content

See docs/user/installation.md for detailed instructions.

2. Configure Environment Variables

Create a .env file in your project:

# Required
GITLAB_URL=https://gitlab.example.com
GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx

# Optional
GITLAB_DEFAULT_PROJECT=mygroup/myproject
GITLAB_TIMEOUT=30
GITLAB_VERIFY_SSL=true

3. Configure Claude Code

Add to your Claude Code MCP settings (~/.claude/mcp.json):

{
  "mcpServers": {
    "gitlab": {
      "command": "python",
      "args": ["-m", "gitlab_mcp.server"],
      "env": {
        "GITLAB_URL": "https://gitlab.example.com",
        "GITLAB_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

See docs/user/configuration.md for advanced configuration options.

Verify Installation

# Activate environment (if using venv)
source .venv/bin/activate

# Test GitLab connection
python -c "from gitlab_mcp.client import GitLabClient; client = GitLabClient(); print('Connected!')"

Usage Examples

Search Code Across Projects

# Claude Code can now do:
# "Search for 'authentication' in all repositories"

# This uses the MCP tool:
search_code(query="authentication", scope="global")

Create and Manage Issues

# "Create an issue for the login bug in my-project"
create_issue(
    project_id="mygroup/my-project",
    title="Fix login authentication bug",
    description="Users cannot log in with SSO",
    labels=["bug", "security"]
)

# "Add a comment to issue #42"
add_issue_comment(
    project_id="mygroup/my-project",
    issue_id=42,
    body="This is related to the auth refactoring in MR !123"
)

Manage Merge Requests

# "Create a merge request from feature-branch to main"
create_merge_request(
    project_id="mygroup/my-project",
    source_branch="feature-branch",
    target_branch="main",
    title="Add OAuth2 support",
    description="Implements OAuth2 authentication flow"
)

# "Approve merge request !25"
approve_merge_request(
    project_id="mygroup/my-project",
    mr_iid=25
)

Monitor CI/CD Pipelines

# "Show me the latest pipeline status"
list_pipelines(
    project_id="mygroup/my-project",
    limit=1
)

# "Get logs from the failed job"
get_job_log(
    project_id="mygroup/my-project",
    job_id=12345
)

See docs/user/usage_examples.md for comprehensive examples.

Documentation

User Documentation

• Installation Guide - Complete setup instructions
• Configuration Guide - Configuration options and best practices
• Usage Examples - Real-world usage scenarios
• Troubleshooting - Common issues and solutions

API Reference

• Tools Reference - Complete tool documentation (67 tools)
• GitLab API Mapping - GitLab API endpoint mapping

Architecture

• System Overview - High-level architecture
• Interfaces - Interface contracts
• Data Flow - How data flows through the system

Development

• Development Guide - Ground rules and TDD workflow
• Product Requirements - Complete feature specifications
• Session Management - Development session logs

Development

Setup Development Environment

# Clone repository
git clone https://github.com/wadew/gitlab-mcp.git
cd gitlab-mcp

# Install uv (fast Python package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create virtual environment
uv venv

# Activate virtual environment
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install development dependencies
uv pip install -e ".[dev]"

Running Tests

# Run all tests (unit + e2e)
pytest tests/unit/ tests/e2e/ -v

# Run with coverage
pytest tests/unit/ tests/e2e/ --cov=src/gitlab_mcp --cov-report=term-missing

# Run integration tests (requires GitLab instance)
source .env
export GITLAB_TEST_PROJECT_ID="mcps/gitlab_mcp"
pytest tests/integration/ -v -m integration

# Run specific test types
pytest tests/unit/ -v -m unit
pytest tests/e2e/ -v -m e2e

# Type checking
mypy src/gitlab_mcp

# Code formatting
black src/ tests/

# Linting
ruff check src/ tests/

Quality Standards

This project follows strict TDD practices:

• ✅ Tests first: Write failing tests, then implement
• ✅ 80%+ coverage: Minimum code coverage requirement
• ✅ 100% pass rate: All tests must pass before commit
• ✅ Type safety: Full mypy compliance
• ✅ Code quality: Black formatting, Ruff linting
• ✅ Documentation: Every function, class, and module

See CLAUDE.md for complete development guidelines.

Project Structure

gitlab_mcp/
├── src/gitlab_mcp/              # Source code
│   ├── server.py                # Main MCP server
│   ├── config/                  # Configuration management
│   ├── client/                  # GitLab API client wrapper
│   ├── tools/                   # MCP tool implementations (87 tools)
│   ├── schemas/                 # Pydantic data models
│   └── utils/                   # Shared utilities
├── tests/                       # Test suite (1257 tests)
│   ├── unit/                    # Unit tests (mocked)
│   ├── integration/             # Integration tests (real API)
│   └── e2e/                     # End-to-end MCP tests
├── docs/                        # Documentation
│   ├── user/                    # User guides
│   ├── api/                     # API reference
│   ├── architecture/            # System design
│   └── session_management/      # Development logs
├── CLAUDE.md                    # Development ground rules
├── next_session_plan.md         # Current development state
└── pyproject.toml               # Project metadata

Contributing

We welcome contributions! Before contributing:

1. Read CLAUDE.md for development ground rules
2. Check next_session_plan.md for current work
3. Write tests first (TDD required)
4. Ensure 80%+ coverage and 100% test pass rate
5. Update documentation for user-facing changes
6. Follow type hints and code quality standards

Commit Message Format

<type>(<scope>): <subject>

<body>

Coverage: X% (±Y%)
Tests: N passing

Types: feat, fix, docs, test, refactor, chore

Development Phases

• Phase 1: Foundation (Server, Config, Client, Auth)
• Phase 2: Repository & Issues Tools
• Phase 3: Merge Requests & Pipelines Tools
• Phase 4: Advanced Features (Security, Wikis, etc.)
• Phase 5: Meta-tools & Streamable HTTP Transport
• Phase 6: Public Release (PyPI + GitHub)

Roadmap

v1.1.0 (Next Release)

• Additional GitLab API coverage
• Performance optimization for large repositories
• Enhanced error messages and debugging tools
• WebSocket transport support

License

MIT License - See LICENSE file for details.

Support

• Issues: https://github.com/wadew/gitlab-mcp/issues
• Documentation: https://github.com/wadew/gitlab-mcp#documentation
• MCP Protocol: https://modelcontextprotocol.io

Acknowledgments

Built with:

• Model Context Protocol (MCP) - AI integration protocol
• python-gitlab - GitLab API client
• Pydantic - Data validation
• httpx - Async HTTP client

---

Built with strict TDD practices. 1257 tests. 84% coverage. Production-ready.

Made with care for the GitLab and AI communities.