mcp-gitlab-server

> ⚠️ Development Stage Notice
> This project is currently in development stage. Features and APIs may change without notice. Use with caution in production environments.

GitLab MCP server based on python-gitlab.

Install

Using Personal Access Token (Most Common)

{
  "mcpServers": {
    "GitLab": {
      "command": "uvx",
      "args": [
        "gitlab-mcp-server"
      ],
      "env": {
        "GITLAB_TOKEN": "<your GitLab personal access token>",
        "GITLAB_URL": "https://gitlab.com"
      }
    }
  }
}

Using OAuth2 Token

{
  "mcpServers": {
    "GitLab": {
      "command": "uvx",
      "args": [
        "gitlab-mcp-server"
      ],
      "env": {
        "GITLAB_OAUTH_TOKEN": "<your GitLab OAuth2 token>",
        "GITLAB_URL": "https://gitlab.com"
      }
    }
  }
}

For self-hosted GitLab instances, set GITLAB_URL to your GitLab instance URL (e.g., https://gitlab.example.com). If not set, it defaults to https://gitlab.com.

Authentication

This MCP server supports two authentication methods:

Method 1: Personal Access Token (Recommended for most users)

1. Create a GitLab Personal Access Token:
- Go to GitLab → User Settings → Access Tokens
- Create a token with read_api scope (minimum required)

2. Set the GITLAB_TOKEN environment variable to your token value

Method 2: OAuth2 Token (For OAuth2 applications)

1. If you have an OAuth2 token from a GitLab OAuth2 application flow
2. Set the GITLAB_OAUTH_TOKEN environment variable to your OAuth2 token value

To create an OAuth2 application:
1. Go to GitLab → User Settings → Applications
2. Create a new application with appropriate scopes (read_api minimum)
3. Use the OAuth2 flow to obtain an access token
4. Use that token as GITLAB_OAUTH_TOKEN

Environment Variables

- GITLAB_TOKEN - Your GitLab Personal Access Token (if using personal token auth)
- GITLAB_OAUTH_TOKEN - Your GitLab OAuth2 Token (if using OAuth2 auth)
- GITLAB_URL - GitLab instance URL (defaults to https://gitlab.com)

Note: The server will first check for GITLAB_OAUTH_TOKEN, and if not found, will use GITLAB_TOKEN. You only need to set one of these.

Tools

Repository & Project Management

- list_projects - List GitLab projects accessible to the authenticated user (supports filtering by owned/starred and pagination) - list_groups - List GitLab groups accessible to the authenticated user - list_group_projects - List all projects within a specific GitLab group - get_user_info - Get information about the authenticated user - search_repositories - Search for GitLab repositories by name, description, or keywords - get_repository_details - Get detailed information about a specific repository

Code Access

- read_repository_code - Read the complete code structure and content of a repository with filtering options - read_repository_file - Read the content of a specific file from a repository

Merge Request Analytics

- list_merge_requests - List merge requests for a repository with filtering by state, ordering, and pagination - get_merge_request_analytics - Calculate comprehensive merge request lifetime statistics including average time from creation to merge

Repository Code Reading Features

The MCP server provides powerful code reading capabilities:

read_repository_code

Reads the entire repository structure and file contents with advanced filtering:

- Selective Reading: Include/exclude files using glob patterns (e.g., .py,.js or exclude .log,node_modules/)
- Size Limits: Control maximum files to read and file size limits to prevent overwhelming responses
- Branch/Tag Support: Read from any branch, tag, or commit SHA
- Directory Filtering: Focus on specific directories within the repository
- Smart Filtering: Automatically excludes common build artifacts, logs, and binary files

Example Usage:
- Read only Python files: include_patterns: ".py"
- Exclude tests: exclude_patterns: "test,spec*"
- Read specific directory: path: "src/"
- Different branch: ref: "develop"

read_repository_file

Reads individual files from a repository:

- Single File Access: Get content of specific files quickly
- Metadata Included: File size, encoding, last commit info
- Binary Detection: Safely handles binary files
- Flexible References: Works with branches, tags, or commit SHAs

Limits & Safety:
- Default: Max 50 files, 100KB per file
- Configurable limits to prevent timeouts
- Automatic binary file detection
- Graceful error handling for large repositories

Merge Request Analytics Features

The MCP server provides comprehensive merge request analytics capabilities:

list_merge_requests

Lists merge requests with advanced filtering and sorting:

- State Filtering: Filter by state (opened, closed, merged, all)
- Flexible Sorting: Order by creation date, update date, or title
- Rich Metadata: Includes author, assignees, reviewers, labels, and voting info
- Pagination Support: Control number of results returned

get_merge_request_analytics

Calculates detailed merge request lifetime statistics:

- Lifetime Analysis: Average, median, min/max time from creation to merge
- Statistical Distribution: 25th, 75th, and 90th percentile analysis
- Time Period Control: Analyze MRs from the last N days (default: 90 days)
- Detailed Breakdown: Individual MR details with exact lifetime calculations
- Multiple Time Units: Results provided in both hours and days

Example Questions You Can Answer:
- "What is the average lifetime of an MR in the acapulco repository?"
- "How long do merge requests typically take to get merged?"
- "What's the distribution of merge request lifetimes?"
- "Which merge requests took the longest to merge?"

Analytics Output:
- Average, median, min, max merge times
- Percentile analysis (25th, 75th, 90th)
- Sample merge requests with individual lifetimes
- Complete dataset for further analysis

Development

# Clone the repository
git clone <repo-url>
cd gitlab-mcp-server
Install dependencies
uv sync
Run in development mode
uv run python -m mcp_gitlab_server

Testing Configuration

For development and testing purposes, you can use a local wheel file installation:

MCP Configuration for Testing:

{

  "mcpServers": {

    "GitLab": {

      "command": "uvx",

      "args": [

        "--from", "/path/to/your/gitlab-mcp-server/dist/mcp_gitlab_server-0.1.0-py3-none-any.whl",

        "gitlab-mcp-server"

      ],

      "env": {

        "GITLAB_TOKEN": "your-gitlab-token-here",

        "GITLAB_URL": "https://gitlab.com"

      }

    }

  }

}

Build and Test Steps:

# Build the wheel file

uv build

Test with MCP client (like Claude Desktop)
Update your MCP configuration with the local wheel path
The wheel file will be in ./dist/ directory
For quick testing, verify the server starts:
uv run python -m mcp_gitlab_server