GitLab MCP Server

GitLab MCP Server

An MCP (Model Context Protocol) server that allows LLMs to interact with GitLab. Access issues, merge requests, pipelines, and repository files directly from Claude Code or other MCP-compatible clients.

Features

• Browse and search projects
• View issues and merge requests (including your own and team-labeled)
• Read MR diffs and comments
• Check pipeline status and job logs
• Browse repository files

Setup

1. Install dependencies

make install
# or
uv sync

2. Create GitLab Personal Access Token

1. Go to GitLab → Avatar (top-right) → Edit profile
2. Left sidebar → Access Tokens
3. Click Add new token
4. Configure:

• Token name: e.g., "MCP Server"
• Expiration date: choose as needed
• Scopes:
• read_api (required)
• read_repository (for file content access)

1. Click Create personal access token
2. Copy the token (won't be shown again)

Direct URL: https://gitlab.com/-/user_settings/personal_access_tokens

3. Configure environment

cp .env.example .env

Edit .env with your values:

GITLAB_URL=https://gitlab.com
GITLAB_TOKEN=your-private-token-here
DEFAULT_ASSIGNEE=me

Configuration

| Variable | Description | Default | |----------|-------------|---------| | GITLAB_URL | Your GitLab instance URL | https://gitlab.com | | GITLAB_TOKEN | Personal access token | (required) | | DEFAULT_ASSIGNEE | Username for "my_*" tools filters | me |

Usage

Run directly

uv run python main.py

Run in background

make start    # Start server
make stop     # Stop server
make restart  # Restart server
make status   # Check if running
make logs     # Tail server logs

Add to Claude Code

Create .mcp.json in your project root:

{
  "mcpServers": {
    "gitlab": {
      "command": "uv",
      "args": ["run", "python", "main.py"],
      "cwd": "/path/to/gitlab-mcp-server"
    }
  }
}

Or use the CLI:

claude mcp add gitlab -- uv run python main.py

Verify with /mcp command inside Claude Code.

Test the server

# Test with MCP Inspector
npx @modelcontextprotocol/inspector uv run python main.py

# Test API connection
uv run python -c "
from tools.projects import get_client
with get_client() as client:
    r = client.get('/user')
    print('Authenticated as:', r.json().get('username'))
"

Available Tools

Projects

| Tool | Description | |------|-------------| | list_projects | List accessible projects (search, filter by ownership/membership) | | get_project | Get project details by path |

Issues

| Tool | Description | |------|-------------| | list_issues | List issues in a project (filter by state, labels, search) | | my_issues | List issues assigned to you (uses DEFAULT_ASSIGNEE) | | team_issues | List issues with a team label (default: "RE") | | get_issue | Get issue details including description | | get_issue_comments | Get comments/notes on an issue |

Merge Requests

| Tool | Description | |------|-------------| | list_merge_requests | List MRs in a project (filter by state, branches, search) | | my_merge_requests | List MRs assigned to you | | my_merge_requests_to_review | List MRs where you are a reviewer | | team_merge_requests | List MRs with a team label (default: "RE") | | get_merge_request | Get MR details including description | | get_merge_request_changes | Get MR file diffs | | get_merge_request_comments | Get MR comments/discussions |

Pipelines

| Tool | Description | |------|-------------| | list_pipelines | List pipelines in a project (filter by status, branch) | | get_pipeline_jobs | Get jobs for a pipeline | | get_job_log | Get job log output |

Repository

| Tool | Description | |------|-------------| | list_repository_tree | List files/directories in a repo | | get_file_content | Get file content from a repo |

Project Structure

gitlab-mcp-server/
├── main.py           # Entry point
├── client.py         # HTTP client & settings
├── models.py         # Pydantic models
├── tools/
│   ├── projects.py   # Project tools
│   ├── issues.py     # Issue tools
│   ├── merge_requests.py  # MR tools
│   ├── pipelines.py  # Pipeline tools
│   └── repository.py # Repository tools
├── .env.example      # Environment template
└── Makefile          # Run commands

License

MIT