GitLab MCP Server

GitLab MCP Server

A production-ready Model Context Protocol (MCP) server for GitLab that integrates with GitHub Copilot in IntelliJ IDEA. Automatically detects your GitLab project from git remote, monitors pipeline and job statuses with intelligent polling, and provides reliable API integration with retry logic.

Status: ✅ Fully Verified (35 tests, 100% pass rate)

Quick Start

1. Install Dependencies

# Runtime dependencies
pip install -r requirements.txt

# Development/test dependencies (optional)
pip install -r requirements-dev.txt

2. Configure Environment

# Copy the example configuration
cp .env.example .env

# Edit .env with your GitLab credentials
# GITLAB_URL=https://your-gitlab-instance.com
# GITLAB_TOKEN=glpat-xxx

How to get a GitLab token:

1. GitLab Settings → Personal Access Tokens
2. Create token with scopes: api, read_api, read_repository
3. Copy token value to .env

3. Start the Server

# Using the startup script
./run.sh

# Or directly
python -m src.server

Expected output:

2026-02-10 13:15:30,123 - src.server - INFO - Initializing GitLab MCP server for https://...
2026-02-10 13:15:30,456 - src.server - INFO - GitLab authentication successful
2026-02-10 13:15:30,789 - src.server - INFO - Tools registered successfully
2026-02-10 13:15:30,900 - src.server - INFO - GitLab MCP server started, listening on stdio

4. Configure in IntelliJ IDEA

1. Install GitHub Copilot plugin (if not already installed)
2. Settings → Tools → GitHub Copilot → MCP Servers
3. Add MCP Server:
   • Type: stdio
   • Command: python -m src.server
   • Environment: Point to your .env file

Features

✅ Automatic Project Detection

• No need to specify project path
• Automatically detected from git remote origin
• Works with SSH and HTTPS URLs
• Supports nested GitLab groups

✅ Pipeline Status Monitoring

• Real-time pipeline status
• All job details and statuses
• Automatic branch and commit detection
• Human-readable formatted output

✅ Job Status with Smart Polling

• Polls every 2 seconds for job completion
• Configurable timeout (default 30 seconds)
• Returns intermediate states
• Polling metadata included in response

✅ Reliable API Integration

• 3 retries with exponential backoff (1s, 5s, 9s)
• Handles transient network failures gracefully
• Session-level project ID caching
• Clear error messages for debugging

✅ Self-Hosted GitLab Support

• Works with any self-hosted GitLab instance
• No dependency on gitlab.com
• Full API compatibility

Available Tools

`check_pipeline_status`

Get pipeline status for current project and branch

Input:  working_directory (string)
        Optional: branch (string), commit (string)
Output: Pipeline status report with all jobs

What it does:

• Auto-detects: project, branch, commit from git repository
• Returns: pipeline ID, status, jobs with individual statuses
• Format: Human-readable text report
• Includes: timing, web URLs, stage information

Example:

# In Copilot context:
# "Check the pipeline status for this project"
# → Copilot calls: check_pipeline_status("/path/to/repo")

`check_job_status`

Check specific job status with automatic polling

Input:  working_directory (string)
        job_name (string) OR job_id (integer)
Output: Job status report with polling metadata

What it does:

• Auto-detects: project, pipeline from current branch/commit
• Searches: by job name or numeric job ID
• Polls: every 2 seconds until completion (max 30s)
• Returns: job status, timing, logs URL, polling metadata
• Metadata: is_polling, polling_timeout, polling_duration_seconds

Example:

# In Copilot context:
# "Check the status of the 'test' job"
# → Copilot calls: check_job_status("/path/to/repo", job_name="test")

Project Structure

gitlab-mcp/
├── src/
│   ├── __init__.py
│   ├── server.py              # MCP server entry point
│   ├── mcp_tools.py           # Tool definitions & logic
│   ├── gitlab_client.py       # GitLab API wrapper (retry logic, caching)
│   └── git_utils.py           # Git utilities (URL parsing, branch detection)
│
├── tests/                      # Comprehensive test suite
│   ├── test_gitlab_client.py  # 9 tests for API client
│   ├── test_git_utils.py      # 11 tests for git utilities
│   ├── test_mcp_tools.py      # 10 tests for tool logic
│   ├── test_server.py         # 5 tests for server initialization
│   └── conftest.py            # Pytest configuration
│
├── requirements.txt            # Runtime dependencies
├── requirements-dev.txt        # Test dependencies
├── .env.example               # Configuration template
├── pytest.ini                 # Pytest settings
├── run.sh                     # Startup script
└── README.md                  # This file

Running Tests

Quick Test Run

# Run all tests
python -