GitLab CI MCP Server

Model Context Protocol (MCP) server for GitLab CI/CD pipeline monitoring.

Purpose

Provides AI agents with structured access to GitLab CI/CD pipelines for the egirl-platform project. Enables agents to:

• List recent pipelines
• Get pipeline details and job information
• Retrieve job logs for debugging
• Analyze recent failures
• Extract likely root causes from error logs

Features

Available Tools

Tool	Description
gitlab_list_pipelines	List recent pipelines with status
gitlab_get_pipeline	Get detailed info for a specific pipeline
gitlab_list_jobs	List all jobs in a pipeline
gitlab_get_job_logs	Retrieve logs for a specific job
gitlab_get_recent_failures	Get recent failed pipelines with details
gitlab_find_failure_cause	Analyze failed pipeline and extract error patterns

Intelligent Features

• Error Pattern Extraction: Automatically identifies error lines in logs
• Structured Responses: Returns JSON for easy agent parsing
• Failure Analysis: Groups related failures and extracts root causes
• Auto .env Loading: Automatically loads GITLAB_PAT from project .env file

Installation

# Install dependencies
pnpm install

# Build the server
pnpm run build

Configuration

The server automatically loads .env from the project root, so no manual configuration needed if you have GITLAB_PAT in your .env file.

For Claude Code MCP Configuration

Add to your Claude Code MCP configuration:

{
  "mcpServers": {
    "gitlab-ci": {
      "command": "node",
      "args": [
        "/absolute/path/to/egirl-platform/packages/mcp-gitlab-ci/dist/index.js"
      ]
    }
  }
}

Note: No env section needed - the server loads .env automatically!

Usage

For AI Agents

Agents can invoke MCP tools directly:

// List recent pipelines
gitlab_list_pipelines({ count: 10 })

// Analyze why a pipeline failed
gitlab_find_failure_cause({ pipelineId: "2160207941" })

// Get job logs
gitlab_get_job_logs({
  pipelineId: "2160207941",
  jobNameOrId: "test"
})

Response Format

All tools return structured JSON:

Pipeline List:

{
  "pipelines": [
    {
      "id": 2160207941,
      "status": "failed",
      "ref": "main",
      "sha": "a1b2c3d4",
      "updated_at": "2025-12-09T10:30:00Z",
      "web_url": "https://gitlab.com/..."
    }
  ]
}

Failure Analysis:

{
  "pipeline_id": "2160207941",
  "analysis": [
    {
      "job": {
        "id": 123456,
        "name": "test",
        "stage": "test",
        "failure_reason": "script_failure"
      },
      "extracted_errors": [
        "Error: Cannot find module '@transftw/types'",
        "TypeError: undefined is not a function"
      ]
    }
  ]
}

Environment Variables

Variable	Description	Required
GITLAB_PAT or GPLAT	GitLab Personal Access Token	Yes

The server checks for both GITLAB_PAT (preferred) and GPLAT (legacy).

Token must have read_api scope to access pipeline information.

Architecture

Claude Code Agent
    ↓ (MCP Protocol)
GitLab CI MCP Server (this package)
    ↓ (imports)
@transftw/platform-tools/ci (GitLab API wrapper)
    ↓ (HTTPS)
GitLab API

Troubleshooting

"GPLAT or GITLAB_PAT environment variable not set"

Add GITLAB_PAT=your-token to the project root .env file.

Server not responding

Verify the .env file exists and contains a valid token:

cat .env | grep GITLAB_PAT

Related

• CLI Tool: packages/platform-tools/src/cli/gitlab-ci.ts - Direct CLI access
• API Library: packages/platform-tools/src/lib/ci/gitlab-api.ts - Underlying API wrapper
• Documentation: .claude/instructions/mcp-tools-usage.md - MCP usage guide

---

Last Updated: 2025-12-09 Created By: The Collective Purpose: Enable AI agents to monitor GitLab CI/CD pipelines efficiently