# 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
```bash
# 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:
```json
{
"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:
```typescript
// 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**:
```json
{
"pipelines": [
{
"id": 2160207941,
"status": "failed",
"ref": "main",
"sha": "a1b2c3d4",
"updated_at": "2025-12-09T10:30:00Z",
"web_url": "https://gitlab.com/..."
}
]
}
```
**Failure Analysis**:
```json
{
"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:
```bash
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
