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)
5. Click Create personal access token
6. 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