GitLab Pipeline Analyser MCP Server

A powerful Model Context Protocol (MCP) server designed to enhance AI's ability to analyze and troubleshoot GitLab CI/CD pipelines.

Overview

This server provides intelligent tools and prompts that allow AI assistants to interact with GitLab pipelines, analyze failures, and generate actionable fix recommendations. By following a convention over configuration approach, it automatically discovers your GitLab project from the current working directory's .git/config and validates your .gitlab-ci.yml syntax, providing seamless integration and a streamlined developer experience.

Quick Installation

The GitLab Pipeline Analyser MCP Server can be easily installed and run using npx, or installed locally for development.

Via npx (Recommended for Users)

Run the server directly without local installation:

npx -y @niwelv/gitlab-pipeline-analyser

Local Installation (For Developers)

For local development or if you prefer a local installation:

1. Clone the repository:

   git clone https://gitlab.com/vlewin/gitlab-pipeline-analyser.git
   cd gitlab-pipeline-analyser

2. Install dependencies:

   npm install

Configuration

This section details how to set up and configure the GitLab Pipeline Analyser MCP Server for use with various MCP clients.

Prerequisites

1. MCP Client: Claude Desktop, Gemini Code Assist, VS Code with MCP extension, or any MCP-compatible client.

2. GitLab Personal Access Token: Required for the MCP server to access the GitLab API (e.g., to check pipelines, read logs).

   Important: The GITLAB_PERSONAL_ACCESS_TOKEN is needed for the MCP server to authenticate with the GitLab API to fetch your pipeline data.

   Get your GitLab token from: https://gitlab.com/-/user_settings/personal_access_tokens

   Required token scopes:

   • read_api - Read access to GitLab API
   • read_repository - Read access to repository information

Configuration Steps

1. Configure Your MCP Client

Add the server to your MCP client configuration. The configuration typically involves defining the server's command and environment variables.

For Claude Desktop (.mcp.json or claude_desktop_config.json):

{
  "mcpServers": {
    "gitlab-pipeline-analyser": {
      "command": "npx",
      "args": ["-y", "@niwelv/gitlab-pipeline-analyser"],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "${GITLAB_PERSONAL_ACCESS_TOKEN}",
        "GITLAB_API_URL": "${GITLAB_API_URL:-https://gitlab.com/api/v4}",
        "MCP_DEBUG": "${MCP_DEBUG:-false}"
      }
    }
  }
}

For Gemini Code Assist (.gemini/settings.json):

{
  "mcpServers": {
    "gitlab-pipeline-analyser": {
      "command": "npx",
      "args": ["-y", "@niwelv/gitlab-pipeline-analyser"],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "${GITLAB_PERSONAL_ACCESS_TOKEN}",
        "GITLAB_API_URL": "${GITLAB_API_URL:-https://gitlab.com/api/v4}",
        "MCP_DEBUG": "${MCP_DEBUG:-false}"
      }
    }
  }
}

For VS Code (with MCP Extension - .vscode/mcp.json):

{
  "servers": {
    "gitlab-pipeline-analyser": {
      "command": "npx",
      "args": ["-y", "@niwelv/gitlab-pipeline-analyser"],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "${GITLAB_PERSONAL_ACCESS_TOKEN}",
        "GITLAB_API_URL": "${GITLAB_API_URL:-https://gitlab.com/api/v4}",
        "MCP_DEBUG": "${MCP_DEBUG:-false}"
      }
    }
  }
}

Note: The ${VAR:-default} syntax provides a default value if the environment variable is not set.

2. Create .env in Your Project Directory

In the root directory of your GitLab project (where your .git folder is), create a .env file with your GitLab credentials:

# GitLab API Credentials
GITLAB_PERSONAL_ACCESS_TOKEN=glpat-your-token-here
GITLAB_API_URL=https://gitlab.com/api/v4

3. Add .env to .gitignore

Critical for security: Add .env to your project's .gitignore to prevent accidentally committing your sensitive tokens:

# Environment variables (contains secrets)
.env

Secure Credentials Handling

The server employs a robust mechanism for handling credentials, prioritizing security and flexibility. For a detailed explanation of how environment variables are processed and the fallback mechanisms, please refer to the SECURITY.md document.

For Self-Hosted GitLab

If you are using a self-hosted GitLab instance, update the GITLAB_API_URL in your .env file:

GITLAB_API_URL=https://gitlab.your-company.com/api/v4

The server includes a security feature that validates the API URL domain against your Git remote to prevent accidentally sending CI configuration to the wrong GitLab instance.

Usage

The GitLab Pipeline Analyser MCP Server is designed for ease of use, following a convention over configuration principle. This means it automatically detects your GitLab project from the current working directory's .git/config.

Just ensure you're in your project's root directory when using the tools!

General Workflow

1. Navigate to your GitLab project's root directory:

   cd /path/to/your/gitlab-project

2. Invoke the desired tool or prompt via your MCP client.

Natural Language Interaction

This MCP server is designed to be highly intuitive. You don't always need to provide exact JSON inputs or remember precise parameter names. The underlying AI agent can often understand your intent through natural language.

Key points:

• Optional Parameters: Many tools have optional parameters (like pipeline_id for analyse_pipeline). If omitted, the tool will use sensible defaults (e.g., the latest pipeline for analyse_pipeline).
• Conversational Input: Feel free to describe what you want to achieve in plain English.

Examples:

• Analyze the last pipeline:

  Analyze the last pipeline

  (The agent will automatically call /analyse_pipeline without a pipeline_id.)

• Check status of pipeline 12345:

  Check the status of pipeline 12345

  (The agent will automatically call /check_pipeline_status pipeline_id=12345.)

• List pipelines for the 'main' branch:

  List pipelines for the main branch

  (The agent will automatically call /list_project_pipelines ref=main.)

Example: Analyze a failed pipeline

To analyze a specific failed pipeline, you can provide its ID to the analyse_pipeline tool. You can do this either with a structured JSON input or using natural language:

Structured Input:

{
  "pipeline_id": "12345"
}

Natural Language Input:

Analyze pipeline 12345

The server will then:

1. ✅ Validate environment variables from your MCP client configuration.
2. ✅ Check if the current directory is a Git repository.
3. ✅ Extract GitLab project details from .git/config.
4. ✅ Validate your .gitlab-ci.yml syntax (especially for analyse_pipeline).
5. ✅ Provide actionable error messages if anything is missing or misconfigured.

Features

Tools

All tools automatically detect the GitLab project from your current working directory. Just run from your project root!

1. check_pipeline_status

Check the status of GitLab CI/CD pipelines for the current project.

Parameters:

• branch (optional): Branch name to check pipelines for

Returns: Latest pipeline status including stage information, duration, and web URL.

2. get_pipeline_jobs

Get detailed job information for a specific pipeline.

Parameters:

• pipeline_id (required): Pipeline ID to get jobs for

Returns: Job details including status, duration, failure reasons, and web URLs.

3. list_project_pipelines

List recent pipelines for the current GitLab project with filtering options.

Parameters:

• ref (optional): Branch or tag name to filter by
• status (optional): Pipeline status to filter by (running, pending, success, failed, canceled, skipped)
• per_page (optional): Number of pipelines to return (default: 10, max: 100)

Returns: List of pipelines with basic information.

4. analyse_pipeline

Analyze a pipeline by checking all jobs and identifying root causes of failures. Automatically validates .gitlab-ci.yml syntax.

Parameters:

• pipeline_id (required): Pipeline ID to analyze

Returns: Comprehensive analysis including:

• .gitlab-ci.yml syntax validation (local YAML + GitLab CI Lint API)
• Zero-jobs detection and diagnostics
• Pipeline summary (status, duration, branch, commit)
• Complete list of all jobs
• Jobs breakdown by status
• Failed job details
• Error pattern detection from logs
• Last 20 lines of failed job logs

5. lint_gitlab_ci_config

Lint .gitlab-ci.yml file syntax and semantics without analyzing a specific pipeline.

Parameters: None (auto-detects from current directory)

Returns:

• File existence check
• YAML syntax validation (using js-yaml)
• GitLab CI semantic validation (via GitLab CI Lint API)
• Detailed error and warning messages
• Validation summary

6. verify_available_runners

Fetch and verify available runners for the current project to help diagnose pipeline execution issues.

Parameters: None (auto-detects from current directory)

Returns:

• Total runner count
• Categorized runners (online, offline, stale)
• Runner details (ID, description, name, tags, type)
• Availability summary message

Prompts

fix-pipeline

Generate detailed instructions to fix a failed GitLab CI/CD pipeline.

Arguments:

• pipeline_id (required): The GitLab pipeline ID to analyze and fix

Generates: A comprehensive prompt with:

• Pipeline information
• Jobs summary
• Failed jobs details
• Root cause analysis with log excerpts
• Actionable fix instructions

Key Capabilities

• Convention over configuration: Zero-config auto-detection from current working directory
• Secure credentials handling: Uses MCP client's ${VAR} substitution with .env files
• Automatic project detection: Extracts GitLab project from .git/config
• YAML syntax validation: Validates .gitlab-ci.yml before analyzing failures
• Comprehensive validation: Checks environment variables, git repo, GitLab remote, and CI config
• Error pattern matching: Parses logs for ERROR, FAILED, fatal, exception patterns
• Log analysis: Provides last 20 lines of failed job logs for context
• Status categorization: Groups jobs by status (success, failed, running, pending, canceled, skipped, manual)
• Actionable error messages: Provides step-by-step setup instructions when something is missing
• Direct API access: Uses GitLab REST API for real-time pipeline data
• Domain validation: Prevents sending CI configuration to wrong GitLab instance

Dependencies

• @modelcontextprotocol/sdk ^1.3.0
• dotenv ^17.2.3 (optional, for standalone testing)
• js-yaml ^4.1.0

Security

The GitLab Pipeline Analyser MCP Server is designed with security in mind, especially concerning sensitive GitLab Personal Access Tokens.

✅ Best Practices:

• Store credentials in .env file (gitignored, project-specific)
• Use ${VAR} substitution in .mcp.json / .gemini/settings.json / .vscode/mcp.json (safe to commit)
• Add .env to .gitignore (prevent accidental commits)
• Use separate .env per project (credential isolation)
• Set minimum token scopes (read_api, read_repository only)
• Domain validation prevents cross-instance credential leakage

❌ Never:

• Hardcode tokens in your client configuration files.
• Commit .env to git.
• Share tokens across multiple projects.
• Use overly permissive token scopes.

For a detailed explanation of secure credential handling, including the primary and fallback flows, and troubleshooting common issues, please refer to the dedicated SECURITY.md document.

License

ISC