Fortschrittlicher GitLab MCP-Server

Fortschrittlicher GitLab MCP-Server – 44 Tools für 18 Entitätstypen mit CQRS-Architektur, OAuth 2.1 und mehreren Transportmodi.

Schnellstart

{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": ["-y", "@structured-world/gitlab-mcp"],
      "env": {
        "GITLAB_TOKEN": "your_gitlab_token",
        "GITLAB_API_URL": "https://gitlab.com"
      }
    }
  }
}

Voraussetzungen: Node.js >= 24

Related MCP server: GitLab MCP Server

Highlights

• 44 Tools für 18 Entitätstypen – Projekte, Merge Requests, Pipelines, Arbeitselemente, Wiki und mehr

• CQRS-Architektur – browse_* für Abfragen, manage_* für Befehle

• Verbindungsstabilität – Begrenzter Start, automatische Wiederverbindung mit exponentiellem Backoff, getrennter Modus, wenn GitLab nicht erreichbar ist

• Multi-Instanz-Unterstützung – Verbindung zu mehreren GitLab-Instanzen mit instanzspezifischem OAuth und Ratenbegrenzung

• Mehrere Transportwege – stdio, SSE, StreamableHTTP

• OAuth 2.1 – Benutzerbezogene Authentifizierung über Claude Custom Connector

• Schreibgeschützter Modus – Sicherer Betrieb für Produktionsumgebungen

• Automatische Erkennung – Erkennt GitLab-Konfiguration aus Git-Remotes

• Feingranulare Steuerung – Tool-Gruppen aktivieren/deaktivieren, Aktionen filtern, Beschreibungen anpassen

• Docker-Unterstützung – ghcr.io/structured-world/gitlab-mcp:latest

Dokumentation

Die vollständige Dokumentation finden Sie unter gitlab-mcp.sw.foundation

Automatisch generierte Tool-Referenz

Für die vollständige Tool-Referenz mit Parametern:

# View locally
yarn list-tools --detail

# Generate documentation
yarn list-tools --export --toc > docs/tools/api-reference.md

Siehe die Vollständige API-Referenz für die automatisch generierte Tool-Dokumentation.

Docker

# HTTP mode
docker run -e PORT=3002 -e GITLAB_TOKEN=your_token -p 3333:3002 \
  ghcr.io/structured-world/gitlab-mcp:latest

# stdio mode
docker run -i --rm -e GITLAB_TOKEN=your_token \
  ghcr.io/structured-world/gitlab-mcp:latest

Verbindungsstabilität

Der Server geht elegant mit Problemen bei der GitLab-Konnektivität um:

• Begrenzter Start – Der Server startet innerhalb von GITLAB_INIT_TIMEOUT_MS (Standard 5s), unabhängig von der Verfügbarkeit von GitLab

• Getrennter Modus – Wenn GitLab nicht erreichbar ist (Status disconnected/failed), wird nur das Tool manage_context bereitgestellt, mit lokalen Aktionen wie whoami, switch_profile und set_scope zur Diagnose. Während einer aktiven Wiederverbindung (Status connecting) bleibt die vollständige Tool-Liste verfügbar, damit MCP-Clients während kurzer Ausfälle ihren Tool-Katalog nicht verlieren. MCP-Clients werden über tools/list_changed über Änderungen der Tool-Verfügbarkeit benachrichtigt.

• Automatische Wiederverbindung – Wiederverbindung mit exponentiellem Backoff (5s → 60s) mit ±10% Jitter

• Fehlerklassifizierung – Vorübergehende Fehler (Netzwerk, 5xx, Timeouts) lösen eine automatische Wiederverbindung aus. Authentifizierungs-/Konfigurationsfehler beim Start führen zum Status failed (keine automatische Wiederverbindung). Ein Widerruf des Tokens während einer Sitzung wird über eine authentifizierte HEAD /api/v4/user-Prüfung erkannt, die neben jeder periodischen Gesundheitsprüfung läuft (nur im statischen Token-Modus; im OAuth-Modus übersprungen). Ein 401 oder 403 bei dieser Prüfung versetzt die Instanz sofort in den Status failed.

• Instanz-Gesundheitsmonitor – Jede überwachte Instanz-URL hat ihre eigene XState-Zustandsmaschine. Nicht verfolgte OAuth-URLs werden derzeit als erreichbar durchgereicht.

Feature-Flags

Mitwirken

Siehe CONTRIBUTING.md für Informationen zur Entwicklungseinrichtung, zum Testen und zu PR-Richtlinien.

Unterstützen Sie das Projekt

USDT (TRC-20): TFDsezHa1cBkoeZT5q2T49Wp66K8t2DmdA

Lizenz

Apache License 2.0 – siehe LICENSE für Details.

Basierend auf zereight/gitlab-mcp (MIT). Siehe LICENSE.MIT.