home / mcp / gitlab mcp server

GitLab MCP Server

Provides real-time GitLab pipeline and job status via MCP for IDE integrations with automatic project detection and robust retry logic.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "horodchukanton-gitlab-mcp": {
      "command": "python",
      "args": [
        "-m",
        "src.server"
      ],
      "env": {
        "DEBUG": "false",
        "GITLAB_URL": "https://your-gitlab-instance.com",
        "GITLAB_TOKEN": "glpat-your-token-here"
      }
    }
  }
}

You can run a production-ready MCP server for GitLab that integrates with GitHub Copilot, automatically detects your GitLab project from the Git remote, monitors pipeline and job statuses with intelligent polling, and provides reliable API integration with retry logic. This server empowers you to query pipeline and job status from your IDE and receive clear, human-readable output during development and debugging.

How to use

This MCP server is used by your MCP client (for example, the Copilot plugin in your IDE) to request current pipeline and job statuses from your GitLab projects. The server handles project detection, polling, caching, and retries to deliver reliable information with clear feedback even under transient network conditions.

How to install

Prerequisites: Python is installed on your system, and you can run commands from a shell. You should also have a GitLab instance accessible via a URL and a personal access token with appropriate scopes.

Step 1. Install Python dependencies and prepare the environment.

# Runtime dependencies
pip install -r requirements.txt

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

Step 2. Configure environment variables for GitLab access.

# 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 obtain a GitLab token: 1. Open GitLab Settings → Personal Access Tokens 2. Create a token with scopes: api, read_api, read_repository 3. Copy the token value into the .env file.

Step 3. Start the MCP server.

# Using the startup script
./run.sh

# Or directly
python -m src.server

Step 4. Configure the MCP server in your IDE integration for Copilot.

Type: stdio
Command: python -m src.server
Environment: Point to your .env file

Additional sections

Configuration, security, and troubleshooting details are provided to help you manage the server. You should review environment variables, retry behavior, and polling settings so you can tailor the server to your GitLab setup and network conditions.

Tools and endpoints

The server exposes a set of tooling endpoints that let you check pipeline and job status from your MCP client. These tools are designed to auto-detect the current project and branch from your git repository, and to provide structured, human-readable output with timing and URLs.

Notes on usage

- The server automatically detects your project from the git remote origin and supports SSH and HTTPS URLs. Nested GitLab groups are supported.

- Job polling checks every 2 seconds with a configurable timeout (default 30 seconds). It returns intermediate states and polling metadata.

- API calls include retry logic with exponential backoff (1s, 5s, 9s) to handle transient network issues.

Security and reliability tips

- Store your GitLab token securely and limit its scopes to what is necessary.

- Enable verbose logging during debugging by setting DEBUG to true in the environment.

Available tools

check_pipeline_status

Get pipeline status for the current project and branch. Automatically detects project, branch, and commit from the git repository and returns a human-readable report with pipeline and job details.

check_job_status

Check a specific job status with automatic polling. Polls every 2 seconds until completion (up to a configurable timeout) and includes polling metadata.