GitLab MCP Server

MCP server for GitLab REST API v4 built with fastmcp. Optimized for minimal token usage.

Prerequisites

For end users (Claude/Codex):

• ✅ Python 3.10+ installed on your system
• ✅ GitLab Personal Access Token

That's it! No manual installation needed - everything else is automatic.

How It Works

When you run the server through npx, the Node.js launcher automatically:

1. ✅ Checks for Python - Looks for python3 or python in your PATH
2. ✅ Creates virtual environment - In ~/.cache/gitlab-mcp-server/venv
3. ✅ Installs dependencies - fastmcp from requirements.txt
4. ✅ Caches everything - Fast subsequent launches

First run: ~10-30 seconds (one-time setup) Next runs: Instant (uses cached venv)

If Python is Not Found

If Python 3.10+ is not installed, the launcher will show instructions for your OS:

• macOS: brew install python@3.11 or download from python.org
• Linux: sudo apt install python3 or sudo yum install python3
• Windows: Download from python.org or winget install Python.Python.3.11

You don't need to manually install fastmcp or create virtualenv! The launcher handles that.

Configuration

Claude Code

Add the server using the CLI:

claude mcp add gitlab --transport stdio \
  --env GITLAB_TOKEN=your-gitlab-token \
  --env GITLAB_URL=https://gitlab.com \
  --env GITLAB_TIMEOUT=30 \
  -- npx -y git+https://github.com/YOUR_ORG/YOUR_REPO.git#main

Or add to ~/.claude.json:

{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": ["-y", "git+https://github.com/YOUR_ORG/YOUR_REPO.git#main"],
      "env": {
        "GITLAB_TOKEN": "your-gitlab-token",
        "GITLAB_URL": "https://gitlab.com",
        "GITLAB_TIMEOUT": "30"
      }
    }
  }
}

Codex

Add to ~/.codex/config.toml:

[mcp_servers.gitlab]
command = "npx"
args = ["-y", "git+https://github.com/YOUR_ORG/YOUR_REPO.git#main"]
startup_timeout_sec = 60
enabled = true

[mcp_servers.gitlab.env]
GITLAB_TOKEN = "your-gitlab-token"
GITLAB_URL = "https://gitlab.com"
GITLAB_TIMEOUT = "30"
MCP_TRANSPORT = "stdio"

Note: Replace YOUR_ORG/YOUR_REPO with your GitHub repository path (e.g., myorg/gitlab-mcp-server).

Environment Variables

Variable	Required	Default	Description
GITLAB_TOKEN	Yes	-	GitLab Personal Access Token
GITLAB_URL	No	https://gitlab.com	GitLab instance URL
GITLAB_TIMEOUT	No	30	API timeout in seconds
MCP_TRANSPORT	No	stdio	Transport protocol
GITLAB_MCP_CACHE_DIR	No	~/.cache	Custom cache directory for virtualenv

Available Tools

This server exposes 20+ GitLab operations as MCP tools:

User

• gitlab_whoami - Get current user profile and validate credentials

Projects

• gitlab_list_projects - List GitLab projects (supports search, pagination)
• gitlab_get_project - Get single project details by ID or path

Branches

• gitlab_list_branches - List repository branches in a project

Merge Requests

• gitlab_list_merge_requests - List merge requests (filter by state: opened, merged, closed)
• gitlab_get_merge_request - Get single merge request details
• gitlab_create_merge_request - Create new merge request
• gitlab_merge_merge_request - Merge a merge request
• gitlab_list_merge_request_notes - List comments on a merge request
• gitlab_create_merge_request_note - Add comment to a merge request
• gitlab_list_merge_request_discussions - List discussion threads on a merge request
• gitlab_create_merge_request_discussion_note - Reply to a discussion thread

Issues

• gitlab_list_issues - List issues in a project (filter by state: opened, closed)
• gitlab_create_issue - Create new issue
• gitlab_list_issue_notes - List comments on an issue
• gitlab_create_issue_note - Add comment to an issue

Pipelines & CI/CD

• gitlab_list_pipelines - List CI/CD pipelines (filter by ref, status)
• gitlab_get_pipeline - Get single pipeline details
• gitlab_create_pipeline - Trigger new pipeline
• gitlab_list_pipeline_jobs - List jobs in a pipeline
• gitlab_get_job - Get single job details
• gitlab_play_job - Start a manual job
• gitlab_retry_job - Retry a failed job
• gitlab_cancel_job - Cancel a running/pending job

All tools support GitLab.com and self-hosted GitLab instances via the GITLAB_URL environment variable.

For Developers

If you're developing or testing locally:

# Clone the repo
git clone https://github.com/YOUR_ORG/YOUR_REPO.git
cd YOUR_REPO

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate  # or .venv\Scripts\activate on Windows

# Install dependencies
pip install -r requirements.txt

# Set environment variables
export GITLAB_TOKEN='your-gitlab-token'
export GITLAB_URL='https://gitlab.com'

# Run the server directly
python3 gitlab_mcp_server.py

# Or test via Node.js launcher
node bin/gitlab-mcp-server.js

Note for end users: You don't need to do this! The npx launcher handles everything automatically.