# 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](https://github.com/jlowin/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](https://github.com/astral-sh/uv) package manager
- A GitLab account with a Personal Access Token (PAT)

### Install dependencies

```bash
uv sync
```

### Configure environment

Create a `.env` file in the project root:

```env
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):

```json
{
  "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:

```bash
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:

```bash
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:

```bash
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`)