MCP GitLab CrunchTools

Ein sicherer MCP-Server (Model Context Protocol) für GitLab-Projekte, Merge Requests, Issues, Pipelines und Suche. Funktioniert mit jeder GitLab-Instanz (gitlab.com, selbst gehostet oder Enterprise).

Überblick

Dieser MCP-Server wurde entwickelt, um:

• Standardmäßig sicher zu sein – Umfassende Bedrohungsmodellierung, Eingabevalidierung und Tokenschutz

• Keine Drittanbieter-Dienste – Läuft lokal über stdio, Ihr API-Token verlässt nie Ihren Rechner

• Multi-Instanz – Funktioniert mit gitlab.com, selbst gehostetem GitLab oder Enterprise-Instanzen über konfigurierbare URL

• Plattformübergreifend – Funktioniert auf Linux, macOS und Windows

• Automatisch aktualisiert – GitHub Actions überwachen CVEs und aktualisieren Abhängigkeiten

• Containerisiert – Verfügbar unter quay.io/crunchtools/mcp-gitlab, basierend auf dem Hummingbird Python-Basisimage

Related MCP server: gitlab-mcp-server

Namenskonvention

Warum Hummingbird?

Das Container-Image basiert auf dem Hummingbird Python-Basisimage von Project Hummingbird, das Folgendes bietet:

• Minimale CVE-Exposition – Mit einem minimalen Paketsatz gebaut, reduziert die Angriffsfläche erheblich

• Regelmäßige Updates – Sicherheitspatches werden zeitnah angewendet

• Für Python optimiert – Vorkonfigurierte Python-Umgebung mit uv-Paketmanager

• Produktionsreif – Korrekte Signalbehandlung und Nicht-Root-Benutzer als Standard

Funktionen

Projektverwaltung (5 Tools)

• list_projects – Projekte mit Filterung und Suche auflisten

• get_project – Projektdetails nach ID oder Pfad abrufen

• list_project_branches – Repository-Zweige auflisten

• get_project_branch – Einzelnen Zweig abrufen

• list_project_commits – Commits mit Datums-/Pfadfilterung auflisten

Gruppenverwaltung (3 Tools)

• list_groups – Gruppen mit Filterung auflisten

• get_group – Gruppendetails nach ID oder Pfad abrufen

• list_group_projects – Projekte in einer Gruppe auflisten (mit Untergruppen-Unterstützung)

Merge Requests (7 Tools)

• list_merge_requests – MRs nach Status, Labels, Meilenstein auflisten

• get_merge_request – MR-Details abrufen

• create_merge_request – Neuen MR erstellen

• update_merge_request – MR-Titel, Beschreibung, Status, Zugewiesene aktualisieren

• list_mr_notes – Kommentare zu einem MR auflisten

• create_mr_note – Kommentar zu einem MR hinzufügen

• get_mr_changes – Diff für einen MR abrufen

Issues (6 Tools)

• list_issues – Issues nach Status, Labels, Meilenstein, Zugewiesenem auflisten

• get_issue – Issue-Details abrufen

• create_issue – Neues Issue erstellen

• update_issue – Issue-Titel, Beschreibung, Status, Labels aktualisieren

• list_issue_notes – Kommentare zu einem Issue auflisten

• create_issue_note – Kommentar zu einem Issue hinzufügen

Pipelines (4 Tools)

• list_pipelines – CI/CD-Pipelines mit Statusfilterung auflisten

• get_pipeline – Pipeline-Details abrufen

• list_pipeline_jobs – Jobs in einer Pipeline auflisten

• get_job_log – Job-Log-Ausgabe abrufen

Suche (2 Tools)

• search_global – Über alle zugänglichen GitLab-Ressourcen suchen

• search_project – Innerhalb eines bestimmten Projekts suchen

Installation

Mit uvx (Empfohlen)

uvx mcp-gitlab-crunchtools

Mit pip

pip install mcp-gitlab-crunchtools

Mit Container

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

Konfiguration

Umgebungsvariablen

Erstellen eines persönlichen GitLab-Zugriffstokens

1. Navigieren Sie zu Zugriffstokens

   • Gehen Sie zu https://gitlab.com/-/user_settings/personal_access_tokens

   • Oder: Avatar > Einstellungen > Zugriffstokens

2. Erstellen Sie ein benutzerdefiniertes Token

   • Name: mcp-gitlab-crunchtools

   • Ablauf: Legen Sie ein geeignetes Datum fest (90 Tage empfohlen)

   • Bereiche: Wählen Sie Bereiche basierend auf Ihren Anforderungen

3. Bereichsauswahl

   Bereich	Zugriffsstufe	Fähigkeiten
   read_api	Nur lesen	Projekte, Issues, MRs, Pipelines auflisten/anzeigen
   api	Voller Zugriff	Alle Funktionen einschließlich Erstellen/Aktualisieren

4. Token kopieren und speichern

   • Kopieren Sie das Token sofort (beginnt mit glpat-)

   • Speichern Sie es sicher in einem Passwortmanager

Zu Claude Code hinzufügen

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

Für selbst gehostetes GitLab:

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

Für die 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

Verwendungsbeispiele

Ihre Projekte auflisten

User: List my GitLab projects
Assistant: [calls list_projects with membership=true]

Merge Requests anzeigen

User: Show open merge requests for my-org/backend
Assistant: [calls list_merge_requests with project_id="my-org/backend"]

Ein Issue erstellen

User: Create an issue in my-org/backend titled "Fix login timeout"
Assistant: [calls create_issue with title="Fix login timeout"]

Pipeline-Status prüfen

User: Show failed pipelines for my-org/api
Assistant: [calls list_pipelines with status="failed"]

Code durchsuchen

User: Search for "authentication" in my-org/backend
Assistant: [calls search_project with scope="blobs"]

Sicherheit

Dieser Server wurde mit Sicherheit als primärem Anliegen entwickelt. Siehe SECURITY.md für:

• Bedrohungsmodell und Angriffsvektoren

• Verteidigung in der Tiefe Architektur

• Best Practices für die Token-Behandlung

• Eingabevalidierungsregeln

• Audit-Protokollierung

Wichtige Sicherheitsfunktionen

1. Tokenschutz

   • Als SecretStr gespeichert (wird nie versehentlich protokolliert)

   • Nur als Umgebungsvariable (nie in Dateien oder Argumenten)

   • Aus allen Fehlermeldungen bereinigt

2. Eingabevalidierung

   • Pydantic-Modelle für alle Eingaben

   • Allowlist-Zeichenvalidierung für Projekt-/Gruppen-IDs

   • Schutz vor Pfad-Traversal

3. API-Härtung

   • HTTPS-Erzwingung (außer localhost)

   • TLS-Zertifikatsvalidierung

   • Anforderungs-Timeouts (30s)

   • Antwortgrößenlimits (10MB)

4. Automatisches CVE-Scannen

   • GitHub Actions scannen Abhängigkeiten wöchentlich

   • Container-Sicherheitsscan mit Trivy

   • CodeQL-Analyse für Python

Entwicklung

Einrichtung

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

Tests ausführen

uv run pytest

Lint und Typprüfung

uv run ruff check src tests
uv run mypy src

Container bauen

podman build -t mcp-gitlab .

Lizenz

AGPL-3.0-or-later

Mitwirken

Beiträge sind willkommen! Bitte lesen Sie SECURITY.md, bevor Sie sicherheitsrelevante Änderungen einreichen.

Links

• GitLab REST-API-Dokumentation

• FastMCP-Dokumentation

• MCP-Spezifikation

• crunchtools.com