Content
# 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:
```bash
npm install
```
3. Copy the environment configuration:
```bash
cp env.example .env
```
4. Edit `.env` file with your GitLab configuration:
```env
GITLAB_URL=https://gitlab.com
GITLAB_TOKEN=your_gitlab_access_token_here
DEFAULT_PROJECT_ID=12345 # Optional
```
## Building and Running
1. Build the TypeScript code:
```bash
npm run build
```
2. Start the server:
```bash
npm start
```
Or for development:
```bash
npm run dev
```
## 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:**
```json
{
"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:**
```json
{
"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:**
```json
{
"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:**
```json
{
"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.
