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 - Comprehensive threat modeling, input validation, and token protection

• 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

2. Create a Custom Token

   • Name: mcp-gitlab-crunchtools

   • Expiration: Set an appropriate date (90 days recommended)

   • Scopes: Select scopes based on your needs

3. Scope Selection

   Scope	Access Level	Capabilities
   read_api	Read-only	List/view projects, issues, MRs, pipelines
   api	Full access	All features including create/update

4. 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

2. Input Validation

   • Pydantic models for all inputs

   • Allowlist character validation for project/group IDs

   • Path traversal prevention

3. API Hardening

   • HTTPS enforcement (except localhost)

   • TLS certificate validation

   • Request timeouts (30s)

   • Response size limits (10MB)

4. 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