MCP Gitlab

MCP GitLab CrunchTools

A secure MCP (Model Context Protocol) server for GitLab projects, merge requests, issues, pipelines, and search. Works with any GitLab instance (gitlab.com, self-hosted, or enterprise).

Overview

This MCP server is designed to be:

• Secure by default - documented threat model (see SECURITY.md), Pydantic input validation, and the API token held as a SecretStr to prevent accidental logging
• No third-party services - Runs locally via stdio, your API token never leaves your machine
• Multi-instance - Works with gitlab.com, self-hosted GitLab, or enterprise instances via configurable URL
• Cross-platform - Works on Linux, macOS, and Windows
• Automatically updated - GitHub Actions monitor for CVEs and update dependencies
• Containerized - Available at quay.io/crunchtools/mcp-gitlab built on Hummingbird Python base image

Naming Convention

Why Hummingbird?

The container image is built on the Hummingbird Python base image from Project Hummingbird, which provides:

• Minimal CVE exposure - Built with a minimal package set, dramatically reducing the attack surface
• Regular updates - Security patches are applied promptly
• Optimized for Python - Pre-configured Python environment with uv package manager
• Production-ready - Proper signal handling and non-root user defaults

Features

Project Management (5 tools)

• list_projects - List projects with filtering and search
• get_project - Get project details by ID or path
• list_project_branches - List repository branches
• get_project_branch - Get a single branch
• list_project_commits - List commits with date/path filtering

Group Management (3 tools)

• list_groups - List groups with filtering
• get_group - Get group details by ID or path
• list_group_projects - List projects in a group (with subgroup support)

Merge Requests (7 tools)

• list_merge_requests - List MRs by state, labels, milestone
• get_merge_request - Get MR details
• create_merge_request - Create a new MR
• update_merge_request - Update MR title, description, state, assignees
• list_mr_notes - List comments on an MR
• create_mr_note - Add a comment to an MR
• get_mr_changes - Get the diff for an MR

Issues (6 tools)

• list_issues - List issues by state, labels, milestone, assignee
• get_issue - Get issue details
• create_issue - Create a new issue
• update_issue - Update issue title, description, state, labels
• list_issue_notes - List comments on an issue
• create_issue_note - Add a comment to an issue

Pipelines (4 tools)

• list_pipelines - List CI/CD pipelines with status filtering
• get_pipeline - Get pipeline details
• list_pipeline_jobs - List jobs in a pipeline
• get_job_log - Get job log output

Search (2 tools)

• search_global - Search across all accessible GitLab resources
• search_project - Search within a specific project

Installation

With uvx (Recommended)

uvx mcp-gitlab-crunchtools

With pip

pip install mcp-gitlab-crunchtools

With Container

podman run -e GITLAB_TOKEN=your_token \

quay.io/crunchtools/mcp-gitlab

Configuration

Environment Variables

Creating a GitLab Personal Access Token

1. Navigate to Access Tokens

• Go to https://gitlab.com/-/user_settings/personal_access_tokens
• Or: Avatar > Preferences > Access Tokens

1. Create a Custom Token

• Name: mcp-gitlab-crunchtools
• Expiration: Set an appropriate date (90 days recommended)
• Scopes: Select scopes based on your needs

1. Scope Selection

1. Copy and Store Token

• Copy the token immediately (starts with glpat-)
• Store securely in a password manager

Add to Claude Code

claude mcp add mcp-gitlab-crunchtools \

--env GITLAB_TOKEN=your_token_here \ -- uvx mcp-gitlab-crunchtools

For self-hosted GitLab:

claude mcp add mcp-gitlab-crunchtools \

--env GITLAB_TOKEN=your_token_here \ --env GITLAB_URL=https://gitlab.example.com \ -- uvx mcp-gitlab-crunchtools

For the container version:

claude mcp add mcp-gitlab-crunchtools \

--env GITLAB_TOKEN=your_token_here \ -- podman run -i --rm -e GITLAB_TOKEN quay.io/crunchtools/mcp-gitlab

Usage Examples

List Your Projects

User: List my GitLab projects

Assistant: [calls list_projects with membership=true]

View Merge Requests

User: Show open merge requests for my-org/backend

Assistant: [calls list_merge_requests with project_id="my-org/backend"]

Create an Issue

User: Create an issue in my-org/backend titled "Fix login timeout"

Assistant: [calls create_issue with title="Fix login timeout"]

Check Pipeline Status

User: Show failed pipelines for my-org/api

Assistant: [calls list_pipelines with status="failed"]

Search Code

User: Search for "authentication" in my-org/backend

Assistant: [calls search_project with scope="blobs"]

Security

This server was designed with security as a primary concern. See SECURITY.md for:

• Threat model and attack vectors
• Defense in depth architecture
• Token handling best practices
• Input validation rules
• Audit logging

Key Security Features

1. Token Protection

• Stored as SecretStr (never accidentally logged)
• Environment variable only (never in files or args)
• Sanitized from all error messages

1. Input Validation

• Pydantic models for all inputs
• Allowlist character validation for project/group IDs
• Path traversal prevention

1. API Hardening

• HTTPS enforcement (except localhost)
• TLS certificate validation
• Request timeouts (30s)
• Response size limits (10MB)

1. Automated CVE Scanning

• GitHub Actions scan dependencies weekly
• Container security scanning with Trivy
• CodeQL analysis for Python

Development

Setup

git clone https://github.com/crunchtools/mcp-gitlab.git

cd mcp-gitlab uv sync

Run Tests

uv run pytest

Lint and Type Check

uv run ruff check src tests

uv run mypy src

Build Container

podman build -t mcp-gitlab .

License

AGPL-3.0-or-later

Contributing

Contributions welcome! Please read SECURITY.md before submitting security-related changes.

Links

• GitLab REST API Documentation
• FastMCP Documentation
• MCP Specification
• crunchtools.com