Odel
MCP server: One MCP server.

MCP Gitlab

@crunchtoolsMCP server · External

Secure MCP server for GitLab projects, merge requests, issues, and pipelines

Version controlv0.4.1AGPL-3.0Python
Freeno charge per call
How to install

Runs on your machine from its package; the steps are below.

What it does

  1. Reads
  2. Writes
  3. High impact

At most: creates or changes data: records, files, settings.

What it costs

Free

Odel charges nothing per call. The publisher may charge for its own service.

Runs locally over stdio

This server isn't hosted — your MCP client launches it from a package registry. Use one of the commands below, or drop the config into your client (e.g. Claude Desktop).

PyPImcp-gitlab-crunchtoolsv0.4.1

Run

uvx mcp-gitlab-crunchtools

MCP client config

{
  "mcpServers": {
    "mcp-gitlab": {
      "command": "uvx",
      "args": [
        "mcp-gitlab-crunchtools"
      ]
    }
  }
}
README5 min read

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

ComponentName
GitHub repocrunchtools/mcp-gitlab
Containerquay.io/crunchtools/mcp-gitlab
Python package (PyPI)mcp-gitlab-crunchtools
CLI commandmcp-gitlab-crunchtools
Module importmcp_gitlab_crunchtools

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)

bash
uvx mcp-gitlab-crunchtools

With pip

bash
pip install mcp-gitlab-crunchtools

With Container

bash
podman run -e GITLAB_TOKEN=your_token \
    quay.io/crunchtools/mcp-gitlab

Configuration

Environment Variables

VariableRequiredDefaultDescription
GITLAB_TOKENYes—Personal Access Token
GITLAB_URLNohttps://gitlab.comGitLab instance URL
SSL_CERT_FILENo—Custom CA bundle path, for self-hosted GitLab with an internal CA
GITLAB_SSL_VERIFYNotrueSet false to disable TLS verification (not recommended)

Creating a GitLab Personal Access Token

  1. Navigate to 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

    ScopeAccess LevelCapabilities
    read_apiRead-onlyList/view projects, issues, MRs, pipelines
    apiFull accessAll 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

bash
claude mcp add mcp-gitlab-crunchtools \
    --env GITLAB_TOKEN=your_token_here \
    -- uvx mcp-gitlab-crunchtools

For self-hosted GitLab:

bash
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:

bash
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

bash
git clone https://github.com/crunchtools/mcp-gitlab.git
cd mcp-gitlab
uv sync

Run Tests

bash
uv run pytest

Lint and Type Check

bash
uv run ruff check src tests
uv run mypy src

Build Container

bash
podman build -t mcp-gitlab .

License

AGPL-3.0-or-later

Contributing

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

Links

Similar modules

Browse Version control