GitLab MCP Server
A Model Context Protocol (MCP) server that provides GitLab integration tools for Claude Code. Interact with GitLab projects, issues, epics, and CI/CD pipelines directly from Claude.
Features
- Issue Management: List, create, update issues, and add comments
- Label Management: List and manage project labels with filtering
- Project Management: View and update project descriptions and topics
- Project Discovery: List all projects of a group recursively, including every subgroup
- Epic Management: List and create epics (Premium/Ultimate tier)
- CI/CD Integration: Monitor pipelines, view job logs, and download traces
- Direct Project Access: Use project paths (namespace/project-name) without ID resolution
- MCP Architecture: Seamless integration with Claude Code via stdio communication
Quick Start
Prerequisites
- GitLab personal access token with
api,read_api, andwrite_apiscopes - Claude Code CLI installed
- Docker (optional, for containerized deployment)
Installation
# Install via Homebrew (Recommended for macOS/Linux)
brew tap sgaunet/homebrew-tools
brew install sgaunet/tools/gitlab-mcp
Configuration
# Set your GitLab token
export GITLAB_TOKEN=your_personal_access_token
# Optional: For self-hosted GitLab
export GITLAB_URI=https://your.gitlab.instance
Add to Claude Code
Register the server once for all your projects (-s user):
claude mcp add gitlab-mcp -s user -- gitlab-mcp
This assumes gitlab-mcp is in your PATH (the case after a Homebrew install). If Claude Code
cannot find the binary, pass the absolute path instead:
# Apple Silicon Mac
claude mcp add gitlab-mcp -s user -- /opt/homebrew/bin/gitlab-mcp
# Intel Mac / Linux
claude mcp add gitlab-mcp -s user -- /usr/local/bin/gitlab-mcp
Pass the token explicitly with -e if it isn't exported in the environment Claude Code inherits:
claude mcp add gitlab-mcp -s user \
-e GITLAB_TOKEN=your_personal_access_token \
-e GITLAB_URI=https://your.gitlab.instance \
-- gitlab-mcp
Verify the server is connected:
claude mcp list
Other scopes: -s local (current project only, default) or -s project (shared via the project's
.mcp.json). See the setup guide for Docker-based
registration and manual mcp.json configuration.
CLI Flags (Optional)
Optimize token usage by disabling tool categories you don't need:
# Example: CI/CD debugging only
gitlab-mcp --no-issues --no-labels --no-project-metadata --no-epics
# Example: Issue management only
gitlab-mcp --no-project-metadata --no-epics --no-pipelines
Append the flags after the -- separator when registering the server:
claude mcp add gitlab-mcp -s user -- gitlab-mcp --no-epics --no-pipelines
Available flags: --no-issues, --no-labels, --no-project-metadata, --no-epics, --no-pipelines, --no-merge-requests, --no-projects
First Usage
List all open issues for project myorg/myproject
Create an issue with title "Bug fix needed" for project myorg/myproject
Get the latest pipeline for myorg/myproject
List all projects of the myorg group
Documentation
- Setup Guide - Installation, configuration, and Claude Code integration
- Docker Deployment - Container-based deployment and Docker Compose
- Tool Reference - Complete documentation for all available tools
- Development Guide - Contributing, testing, and development workflow
- Troubleshooting - Common issues and solutions
- Contributing - How to contribute to the project
Available Tools
License
MIT License. See LICENSE for details.
Support
For issues, questions, or feature requests, please create an issue in the repository.
