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 -m pytest tests/ -v

# Quick summary
python -m pytest tests/ -q

Test Coverage

• Total Tests: 35 (100% pass rate ✅)
• Modules Tested: All 4 core modules
  • gitlab_client.py: 9 tests (API client, retry logic, caching)
  • git_utils.py: 11 tests (URL parsing, validation)
  • mcp_tools.py: 10 tests (polling, formatting, logic)
  • server.py: 5 tests (initialization, configuration)

Running Specific Tests

# Test GitLab client
python -m pytest tests/test_gitlab_client.py -v

# Test git utilities
python -m pytest tests/test_git_utils.py -v

# Test MCP tools
python -m pytest tests/test_mcp_tools.py -v

# Test server
python -m pytest tests/test_server.py -v

# Run with coverage
python -m pytest tests/ --cov=src --cov-report=html

---

Configuration

Environment Variables

Create .env file with:

# Required
GITLAB_URL=https://your-gitlab-instance.com
GITLAB_TOKEN=glpat-your-token-here

# Optional
DEBUG=false  # Set to 'true' for verbose logging

Retry Logic Configuration

The client automatically retries failed API calls:

• Total attempts: 3 (initial + 2 retries)
• Backoff delays: 1s, 5s, 9s
• Applies to: All GitLab API calls

Job Polling Configuration

Configure polling behavior via code:

# Default settings
_poll_job_status(client, project, job_name, job_id,
                timeout_seconds=30,    # Max wait time
                poll_interval=2.0)      # Check every 2 seconds

---

Architecture

┌─────────────────────────────────────────────┐
│  IntelliJ IDEA + GitHub Copilot Plugin      │
│  (IDE Client)                               │
└──────────────────┬──────────────────────────┘
                   │ (stdio transport)
                   │ (MCP Protocol)
                   │
┌──────────────────▼──────────────────────────┐
│  FastMCP Server (Python)                    │
│  ┌────────────────────────────────────────┐ │
│  │ MCP Tools                              │ │
│  │ • check_pipeline_status                │ │
│  │ • check_job_status (with polling)      │ │
│  └────────────────────────────────────────┘ │
│  ┌────────────────────────────────────────┐ │
│  │ GitLab Client                          │ │
│  │ • Session-based caching                │ │
│  │ • Retry logic (1s, 5s, 9s backoff)     │ │
│  │ • Pipeline/job/MR queries              │ │
│  └────────────────────────────────────────┘ │
│  ┌────────────────────────────────────────┐ │
│  │ Git Utilities                          │ │
│  │ • SSH/HTTPS URL parsing                │ │
│  │ • Branch/commit detection              │ │
│  │ • Repository validation                │ │
│  └────────────────────────────────────────┘ │
└──────────────────┬──────────────────────────┘
                   │ (HTTP REST API)
                   │
┌──────────────────▼──────────────────────────┐
│  Self-Hosted GitLab Instance                │
│  (or gitlab.com)                            │
└─────────────────────────────────────────────┘

---

Troubleshooting

Configuration Issues

"GITLAB_URL environment variable is not set"

• Verify .env file exists: ls -la .env
• Check .env has GITLAB_URL: grep GITLAB_URL .env
• Ensure .env is in working directory when running server

"GITLAB_TOKEN environment variable is not set"

• Add GITLAB_TOKEN to .env
• Token format: glpat-xxx (GitLab Personal Access Token)
• Verify token has correct scopes: api, read_api, read_repository

"GitLab authentication successful" but tools fail

• Check GitLab instance is accessible: curl -H "PRIVATE-TOKEN: $TOKEN" $GITLAB_URL/api/v4/user
• Verify token has correct scopes
• Check firewall/network access to GitLab instance

Git Issues

"Not a git repository"

• Ensure you're in a git repository: git remote -v
• Supported remote formats:
  • git@gitlab.host:group/project.git
  • https://gitlab.host/group/project.git
  • https://gitlab.host/group/project (without .git)
  • http://gitlab.host/group/project (HTTP, not HTTPS)

"Unable to parse git remote URL"

• Check git remote format: git remote -v
• Both SSH and HTTPS must be in standard GitLab format
• Nested groups supported: company/team/project

Pipeline/Job Issues

"No pipeline found for branch"

• Verify branch has been pushed: git push
• Check pipeline triggers are configured in GitLab
• Try with explicit commit SHA: check_pipeline_status(dir, commit="abc123")

"Job not found: test"

• Verify job name matches exactly (case-sensitive)
• Check pipeline has jobs (may be empty)
• List jobs: check_pipeline_status(dir) to see all jobs

Job polling times out (30 seconds)

• Job hasn't started within 2-minute window
• Can re-run tool to check current status
• Tool returns last known state even after timeout

Debug Mode

Enable verbose logging:

# In .env
DEBUG=true

# Or as environment variable
DEBUG=true python -m src.server

Check logs during tool invocation for detailed error messages.

---

Verification & Testing

Test Results

============================= 35 passed in 12.73s ===============================
✅ test_git_utils.py         (11 tests)
✅ test_gitlab_client.py      (9 tests)
✅ test_mcp_tools.py         (10 tests)
✅ test_server.py             (5 tests)

What's Tested

• ✅ GitLab API client with mocked responses
• ✅ Retry logic and exponential backoff
• ✅ Project ID caching mechanism
• ✅ Git URL parsing (SSH, HTTPS, nested groups)
• ✅ Job polling with timeout
• ✅ Response formatting
• ✅ Server initialization and configuration
• ✅ Error handling and validation

Testing Without Real GitLab Instance

All tests use mocked GitLab API (no real API calls needed):

python -m pytest tests/ -v

---

Performance

Typical Response Times

• First API call: 1-3 seconds (depends on network)
• Subsequent calls: <500ms (cached project ID)
• Job polling: 2-second intervals
• Total test suite: ~13 seconds

Caching Strategy

• Project ID: Cached per server session
• Reset: Server restart clears cache
• Benefit: Reduces API calls for repeated operations

---

Implementation Details

Retry Logic

Attempt 1: Immediate call
  ↓ (fails)
Wait 1 second
Attempt 2: Retry
  ↓ (fails)
Wait 5 seconds
Attempt 3: Final retry
  ↓ (fails)
Raise GitLabClientError

URL Parsing Examples

SSH:   git@gitlab.com:group/project.git          → group/project
HTTPS: https://gitlab.com/group/project.git      → group/project
HTTPS: https://gitlab.com/group/project          → group/project
SSH:   git@host:company/team/subteam/project.git → company/team/subteam/project

Job Polling Behavior

Initial check: Get job status immediately
  ↓
If terminal state (success/failed/canceled/skipped): Return
  ↓
If not started: Polling loop
  ├─ Check every 2 seconds
  ├─ Max 30 seconds total
  └─ Return with polling_timeout flag if timeout occurs

---

Supported Git Repositories

✅ Self-hosted GitLab instances (any version) ✅ gitlab.com (public GitLab) ✅ Nested groups (company/team/project/...) ✅ SSH and HTTPS remotes

❌ Not supported: GitHub, Bitbucket, etc. (GitLab only)

---

What to Do Next

1. Local Testing

# Test git utilities
python -c "
from src.git_utils import get_project_path_from_working_dir
print(get_project_path_from_working_dir('.'))
"

2. Test GitLab Connection

python -c "
import os
from dotenv import load_dotenv
from src.gitlab_client import GitLabClient
load_dotenv()
client = GitLabClient(os.getenv('GITLAB_URL'), os.getenv('GITLAB_TOKEN'))
client.gl.auth()
print('✓ GitLab auth successful')
"

3. Start the Server

./run.sh
# Then configure in IntelliJ IDEA GitHub Copilot plugin

4. Use with Copilot

In IntelliJ IDEA with Copilot:

• "Check the pipeline status"
• "What's the status of the test job?"
• "Show me the latest pipeline"

---

Contributing

To add tests or features:

1. Create test file in tests/ directory
2. Use mocking for GitLab API: patch('src.gitlab_client.gitlab.Gitlab')
3. Run tests: python -m pytest tests/ -v
4. Ensure all tests pass before committing

---

Dependencies

Runtime

• fastmcp>=2.14.0 - Model Context Protocol server
• python-gitlab>=4.0.0 - GitLab API client
• python-dotenv>=1.0.0 - Environment variable loading
• GitPython>=3.1.0 - Git operations

Development/Testing

• pytest>=8.0.0 - Testing framework
• requests-mock>=1.11.0 - HTTP mocking (optional)

---

Implementation Status

Feature	Status	Tests
Pipeline status monitoring	✅ Complete	4
Job status lookup	✅ Complete	5
Job polling	✅ Complete	4
Git URL parsing	✅ Complete	8
Retry logic	✅ Complete	1
Error handling	✅ Complete	3
Server initialization	✅ Complete	5
Configuration validation	✅ Complete	5

---

Support

For issues or questions:

1. Enable debug logging: Set DEBUG=true in .env
2. Check logs: Review server output during tool invocation
3. Verify setup: Follow troubleshooting section above
4. Review tests: Check tests/ for usage examples
5. Check git remote: git remote -v must be valid GitLab URL

---

License

[Add your license here]

---

Last Verified: February 10, 2026
Test Suite: 35/35 passing ✅
Status: Production Ready 🚀