Skip to main content
Glama
horodchukanton

GitLab MCP Server

by horodchukanton
OverviewSchemaRelated ServersScoreDiscussions
Python
Remote

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 🚀

This server cannot be installed

-
security - not tested
F
license - not found
-
quality - not tested

How are these scores calculated?

Resources

New MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/horodchukanton/gitlab-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server