GitLab MCP

A Model Context Protocol (MCP) server that exposes GitLab project management capabilities to AI assistants like Claude.

Overview

This project provides an MCP server built with FastMCP that connects to a GitLab project and exposes tools for managing issues, milestones, members, and generating team reports — all accessible directly from Claude Desktop or Claude Code.

Goal

The goal is to give AI assistants a structured, read/write interface into GitLab so that team leads and developers can manage their projects through natural language. Instead of navigating the GitLab UI, you can ask Claude to list open issues, create a new issue, check milestone progress, or generate a team workload report.

Available Tools

Tool	Description
get_project_overview	Fetch high-level project info
list_project_members	List all members of the project
list_issues	List issues with optional filters
get_issue	Get details of a specific issue
create_issue	Create a new issue
edit_issue	Edit an existing issue
add_issue_comment	Add a comment to an issue
list_milestones	List project milestones
get_milestone	Get details of a specific milestone
get_team_workload	Report on issue distribution across members
get_milestone_report	Summary report for a milestone

Setup

Prerequisites

• Python 3.14+
• uv package manager
• A GitLab account with a Personal Access Token (PAT)

Install dependencies

uv sync

Configure environment

Create a .env file in the project root:

GITLAB_URL=https://gitlab.com
GITLAB_PAT=your_personal_access_token
GITLAB_PROJECT_ID=your_project_id

• GITLAB_URL: Your GitLab instance URL (use https://gitlab.com for GitLab.com)
• GITLAB_PAT: A GitLab Personal Access Token with api scope
• GITLAB_PROJECT_ID: The numeric ID or namespace/project path of your project

Claude Desktop Setup

Add the following to your Claude Desktop config file (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "gitlab": {
      "command": "uv",
      "args": [
        "--project",
        "/absolute/path/to/gitlab-mcp",
        "run",
        "/absolute/path/to/gitlab-mcp/main.py"
      ],
      "cwd": "/absolute/path/to/gitlab-mcp",
      "env": { // Or put into .env
        "GITLAB_URL": "https://gitlab.com",
        "GITLAB_PAT": "your_personal_access_token",
        "GITLAB_PROJECT_ID": "your_project_id"
      }
    }
  }
}

Restart Claude Desktop after saving the config. The GitLab tools will appear in Claude's tool list.

Claude Code Setup

Add the MCP server to Claude Code by running:

claude mcp add gitlab -- uv --directory /absolute/path/to/gitlab-mcp run main.py

Then set the required environment variables either in your shell profile or by passing them inline:

GITLAB_URL=https://gitlab.com \
GITLAB_PAT=your_personal_access_token \
GITLAB_PROJECT_ID=your_project_id \
claude mcp add gitlab -- uv --directory /absolute/path/to/gitlab-mcp run main.py

You can verify the server is registered with:

claude mcp list

Todo

• [ ] Merge Request support — Add tools for listing, creating, reviewing, and merging MRs (list_merge_requests, get_merge_request, create_merge_request, approve_merge_request, merge)