GitLab MCP Server

A Model Context Protocol (MCP) server that provides GitLab API integration capabilities. This server allows you to interact with GitLab projects, pipelines, and jobs through the standardized MCP interface.

Features

• Get Project Information: Retrieve detailed information about GitLab projects
• Get Pipeline Data: Fetch pipeline information for projects
• Get Latest Pipelines: Retrieve the latest X number of pipelines with streamlined output
• Get Job Data: Retrieve job data with automatic pagination (max 100 jobs per page)
• Keyset-based Pagination: Efficient pagination for large datasets following GitLab API best practices
• Authentication: Secure authentication using GitLab personal access tokens

Prerequisites

• Node.js 18+
• A GitLab personal access token with appropriate permissions
• Access to a GitLab instance (GitLab.com or self-hosted)

Installation

1. Clone or download this repository

2. Install dependencies:

   npm install
   

   Copy

3. Copy the environment configuration:

   cp env.example .env
   

   Copy

4. Edit .env file with your GitLab configuration:

   GITLAB_URL=https://gitlab.com
   GITLAB_TOKEN=your_gitlab_access_token_here
   DEFAULT_PROJECT_ID=12345  # Optional
   

   Copy

Building and Running

1. Build the TypeScript code:

   npm run build
   

   Copy

2. Start the server:

   npm start
   

   Copy

   Or for development:

   npm run dev
   

   Copy

GitLab Token Setup

1. Go to GitLab → Settings → Access Tokens
2. Create a new personal access token with the following scopes:
   • read_api - For reading project information
   • read_repository - For accessing repository data
   • read_user - For user information

Available Tools

1. get_project_info

Get information about a GitLab project.

Parameters:

• projectId (string, required): The project ID or path (e.g., "123" or "group/project")

Example:

{
  "projectId": "gitlab-org/gitlab"
}

2. get_pipeline_data

Get pipeline data for a GitLab project.

Parameters:

• projectId (string, required): The project ID or path
• pipelineId (string, optional): Specific pipeline ID to retrieve
• limit (number, optional): Maximum number of pipelines to retrieve (default: 20)

Example:

{
  "projectId": "123",
  "limit": 50
}

3. get_latest_pipelines

Get the latest X number of pipelines for a GitLab project, ordered by creation date.

Parameters:

• projectId (string, required): The project ID or path
• count (number, optional): Number of latest pipelines to retrieve (default: 5, max: 50)

Features:

• Focused on retrieving recent pipeline activity
• Streamlined output with key pipeline information
• Includes pipeline rank, status, branch, author, and duration
• Optimized for quick pipeline status overview

Example:

{
  "projectId": "123",
  "count": 10
}

4. get_job_data

Get job data for a GitLab project with automatic pagination.

Parameters:

• projectId (string, required): The project ID or path
• pipelineId (string, optional): Specific pipeline ID to get jobs for
• limit (number, optional): Maximum number of jobs to retrieve (default: 1000)

Features:

• Automatically handles pagination using keyset-based pagination
• Retrieves up to 100 jobs per page (GitLab API maximum)
• Provides job statistics and summaries
• Supports both project-wide and pipeline-specific job retrieval

Example:

{
  "projectId": "123",
  "limit": 500
}

API Rate Limits

This server follows GitLab API rate limiting best practices:

• Uses keyset-based pagination for efficient data retrieval
• Respects GitLab's rate limits (typically 2000 requests per minute for authenticated users)
• Implements proper error handling for rate limit responses

Architecture

The server follows MCP architecture principles:

• MCP Host: Any MCP-compatible client (e.g., Claude Desktop, IDEs)
• MCP Client: The protocol client that connects to this server
• MCP Server: This GitLab integration server
• GitLab API: The remote service providing GitLab data

Error Handling

The server provides comprehensive error handling:

• Authentication errors
• Project not found errors
• Rate limiting errors
• Network connectivity issues
• Invalid parameter validation

Development

Project Structure

├── src/
│   ├── types.ts          # TypeScript type definitions
│   ├── gitlab-client.ts  # GitLab API client implementation
│   └── index.ts          # Main MCP server implementation
├── build/                # Compiled JavaScript (generated)
├── package.json
├── tsconfig.json
├── env.example
└── README.md

Adding New Features

1. Define new types in src/types.ts
2. Implement GitLab API methods in src/gitlab-client.ts
3. Add MCP tool handlers in src/index.ts
4. Update this README

Troubleshooting

Connection Issues

• Verify your GITLAB_TOKEN is valid and has appropriate permissions
• Check if GITLAB_URL is correct (include protocol: https://)
• Ensure network connectivity to your GitLab instance

Tool Execution Errors

• Check that project IDs/paths are correct
• Verify you have access to the requested projects
• Review GitLab API documentation for parameter requirements

Performance Issues

• Use appropriate limit parameters to avoid large data transfers
• Consider filtering by specific pipeline IDs when possible
• Monitor rate limit responses

Security

• Store GitLab tokens securely in environment variables
• Never commit tokens to version control
• Use tokens with minimal required permissions
• Regularly rotate access tokens

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

MIT License - see LICENSE file for details.