GitLab MCP

GitLab MCP ist ein harness-neutraler Model-Context-Protocol-Server mit gemeinsamen Agent Skills für die Arbeit mit GitLab-Repositories. Codex, Claude Code, Cline und Pi sind unterstützte Distributionen desselben kanonischen MCP-Kerns und keine separaten GitLab-Implementierungen. ChatGPT kann denselben Kern über die entfernte Streamable-HTTP-Bereitstellung nutzen.

Das Projekt bietet:

• einen eigenständigen GitLab-MCP-Server mit typisierten Tools;

• eine allgemeine $gitlab-Skill;

• $gl-address-comments für ungelöste Merge-Request-Diskussionen;

• $gl-fix-ci für Pipeline- und Job-Diagnose;

• $gl-publish für die Auslieferung von Branch, Commit, Push und Entwurfs-MR;

• GitLab-native Runner-, CI-Lint-, Governance-, Tag-, Release- und Pipeline-Zeitplan-Workflows sowie geheimnissichere Projekt- und Gruppen-CI/CD-Variablenverwaltung;

• schlanke Codex-, Claude-Code-, Cline- und Pi-Distributionen, die denselben kanonischen Kern und dieselben Agent Skills wiederverwenden; und

• zustandslosen Streamable-HTTP-Transport und OAuth-geschützte Ressourcen-Metadaten für die ChatGPT-Bereitstellung.

Einstieg hier

Der Dokumentationsindex verlinkt den vollständigen Satz an Benutzer-, Betreiber-, Entwickler-, Sicherheits-, Kompatibilitäts- und Release-Dokumentation.

Related MCP server: GitLab MCP Server

Schnellstart

Für eine lokale Quellinstallation verwenden Sie Node.js 22 oder neuer und erstellen und verifizieren Sie dann den kanonischen MCP-Kern:

npm.cmd ci
npm.cmd test
npm.cmd run build

Wählen Sie den Adapter, der zum Harness passt. Alle vier unterstützten Adapter verwenden dasselbe gebaute MCP-Bundle und dieselben kanonischen Agent Skills.

Für Codex fügen Sie dieses Repository einem vertrauenswürdigen lokalen Marktplatz hinzu, installieren Sie das gitlab-Plugin und starten Sie Codex neu oder aktualisieren Sie es. Das etablierte Root-Codex-Manifest, .mcp.json, der Preload und der Artefaktname bleiben unterstützte Kompatibilitätsoberflächen. Konfigurieren Sie die GitLab-Instanz und den Token in der Umgebung, die Codex startet:

$env:GITLAB_URL = "https://gitlab.example.com"
$env:GITLAB_TOKEN = "<token>"

Starten Sie eine neue Konversation und bitten Sie Codex, die Verbindung zu bestätigen, zum Beispiel:

Use GitLab to tell me which account and instance are connected.

Claude-Code-Benutzer können die materialisierte native Plugin-Distribution laden, die denselben MCP-Server und dieselben kanonischen Agent Skills bündelt. Siehe den Claude-Code-Adapter-Leitfaden für Paketvalidierung, --plugin-dir-Laden und marktplatzkompatibles Layout.

Cline-Benutzer können dasselbe kanonische MCP-Bundle über stdio verwenden und die kanonischen Agent Skills installieren, ohne eine separate GitLab-Implementierung. Siehe den Cline-Adapter-Leitfaden für IDE- und CLI-Einrichtung.

Pi-Benutzer können das dedizierte Pi-Paket installieren, das das kanonische MCP-Tool-Inventar über eine dünne stdio-Brücke registriert und dieselben Agent Skills bereitstellt. Siehe den Pi-Adapter-Leitfaden für Paketinstallation, Laufzeitabhängigkeitsbehandlung und Brücken-Einschränkungen.

Siehe den Benutzerleitfaden für Token-Anleitung mit geringsten Rechten, gängige GitLab-Workflows und die ChatGPT-HTTP-Bereitstellung.

Anforderungen

• Node.js 22 oder neuer

• eine GitLab.com-, GitLab-Dedicated- oder selbstverwaltete GitLab-Instanz

• für lokale stdio-Nutzung ein GitLab-Token mit den Mindest-Scopes, die für die von Ihnen beabsichtigten Operationen erforderlich sind

Erstellen und verifizieren

npm.cmd install
npm.cmd test
npm.cmd run adapters:check
npm.cmd run check:bundle
npm.cmd run build
npm.cmd run validate:codex
npm.cmd run validate:claude
npm.cmd run validate:cline
npm.cmd run validate:pi
npm.cmd run check:versions
npm.cmd run check:gitlab-oauth -- https://gitlab.example.com

Der kanonische MCP-Bundle-Pfad wird durch distribution.json definiert; die aktuelle Konfiguration baut server/dist/gitlab-mcp.cjs. Das MCP-Bundle selbst wird generiert und in der Quellverwaltung ignoriert und dann in Release-Artefakte aufgenommen. Harness-Pakete können weiterhin eine Harness-seitige Laufzeitabhängigkeit deklarieren; das Pi-Paket verwendet zum Beispiel das MCP-SDK, um Pi an diesen gebündelten Server zu verbinden.

distribution.json ist die maßgebliche Quelle für gemeinsame Distributions-Metadaten, einschließlich der neutralen gitlab-Distributionskennung, Basisversion, Beschreibung, Lizenz, des kanonischen MCP-Bundles und des Skills-Pfads. Nach einer Änderung führen Sie npm run adapters:generate aus und prüfen die generierten Codex/Claude-Code/Cline/Pi-Metadaten. npm run adapters:check lehnt Metadaten-Drift und einen fehlenden, nicht-Verzeichnis- oder Repository-ausbrechenden kanonischen Skills-Pfad ab.

npm run check:bundle führt einen In-Memory-Clean-Build durch und schlägt fehl, wenn das kanonische Bundle harness-spezifische Implementierungsreferenzen enthält. npm run check:versions verifiziert, dass generierte Paket- und Codex-Release-Metadaten mit distribution.json ausgerichtet bleiben. Das Codex-Plugin-Manifest kann Codex-Build-Metadaten nach + anhängen, ohne die Basis-Distributionsversion zu ändern. SERVER_VERSION wird unabhängig vom harness-neutralen MCP-Kern verwaltet und wird nur erhöht, wenn sich die Kernlaufzeit selbst ändert.

Der harness-neutrale Kern und die Adapter-Grenze sind in ADR-001 dokumentiert. Die GEN-08-fokussierten Audit- und Identitätsentscheidungen sind in docs/GENERALISATION_AUDIT.md festgehalten.

Kontinuierliche Integration

GitLab-Merge-Request-, Standard-Branch- und Tag-Pipelines führen Syntaxprüfungen, Tests, Coverage, Dependency-Cruiser, Formatierung/Linting, ein Produktionsabhängigkeits-Audit, einen sauberen Bundle-Build und gebündelte stdio/HTTP-Smoke-Tests durch. GitLab-SAST- und Secret-Detection-Vorlagen sind ebenfalls aktiviert. Codex, Claude Code, Cline und Pi haben jeweils eine fokussierte Adapter-Validierung nach dem kanonischen Build; diese Jobs validieren die Harness-Verpackung und den MCP-Start, ohne die Kern-Node/security-Matrix zu wiederholen.

Tag-Pipelines veröffentlichen zusätzlich das deterministische Codex-Archiv mit seinem CycloneDX-SBOM und SHA256SUMS sowie reproduzierbare Claude-Code-, Cline- und Pi-MCP-+-Skills-Archive mit passenden .sha256-Sidecars als GitLab-Job-Artefakte. Das letzte Release-Set-Gate erfordert genau die vier unterstützten Harnesses und vergleicht deren kanonische MCP-Bundle- und Skills-Digests. Releases gelten erst als vollständig, wenn die Artefakte gemäß docs/PUBLICATION_CHECKLIST.md verifiziert wurden.

Das festgeschriebene Inventar docs/gitlab-tool-contracts.json ruft jedes registrierte Tool mit grenzwertig gültigen Eingaben auf und legt seine Sicherheitsklassifizierung, HTTP-Methode, kodierte Route, Query-/Body-Zuordnung und den begrenzten Antwortmodus fest. Die Coverage deckt jedes Produktionsquellmodul ab und schlägt unter 90 % Zeilen, 80 % Funktionen oder 75 % Zweigen fehl; das Hinzufügen eines Tools ohne Inventarintrag lässt den Test fehlschlagen.

Die Syntax- und Test-Jobs laufen sowohl auf node:22-alpine als auch auf node:24-alpine; der schwellenwertdurchsetzte Coverage-Job läuft auf Node 22. Die Kern-Jobs erfordern einen nicht getaggten Linux-Runner, der diese Images ausführen und die npm-Registry erreichen kann. Die Sicherheitsvorlagen ziehen ihre Analyzer-Images aus der GitLab-Registry. Privilegierter Modus ist für die Kern-Node.js-Jobs nicht erforderlich. Konfigurieren Sie mindestens einen Projekt-, Gruppen- oder Instanz-Runner, der ungetaggte Jobs akzeptiert und Jobs mindestens 10 Minuten lang ausführen lässt, bevor erfolgreiche Pipelines für Merge erforderlich sind.

Lokale Codex-Authentifizierung

Legen Sie die Instanz-URL und den Token in der Umgebung fest, die Codex startet:

$env:GITLAB_URL = "https://gitlab.example.com"
$env:GITLAB_TOKEN = "<token>"

GITLAB_URL muss standardmäßig HTTPS verwenden und lehnt eingebettete Anmeldedaten, Queries und Fragmente ab. Für eine ausdrücklich lokale/private Entwicklungs-GitLab-Instanz, die kein TLS verwenden kann, setzen Sie GITLAB_ALLOW_INSECURE_HTTP=true. Die Überschreibung wird in Produktion und für öffentliche Hostnamen abgelehnt; sie akzeptiert Loopback, private Netzwerk-IPs, Einzel-Label-Hosts und die privaten Entwicklungs-Suffixe .localhost, .local, .internal und .home.arpa.

GITLAB_URL ist standardmäßig https://gitlab.com. Die Codex-.mcp.json startet den gebündelten Server über stdio und lädt den dünnen Codex-Distributionsadapter vor dem harness-neutralen Kern. Tokens werden zur Laufzeit gelesen und niemals in einer Distribution gespeichert.

Verwenden Sie die engsten Token-Scopes, die die Aufgabe abdecken. Nur-Lese-Arbeit kann einen leseorientierten Token verwenden; Repository-, Issue-, Merge-Request- oder CI-Mutationen erfordern die entsprechenden GitLab-API-Berechtigungen.

Fähigkeitserkennung

Rufen Sie get_gitlab_capabilities auf, bevor Sie diagnostizieren, ob eine GitLab-Operation nicht unterstützt, nicht lizenziert, deaktiviert oder für die aktuelle Anmeldedaten nur unzugänglich ist. Es verwendet nur Lese-Anfragen an /user, /version, /metadata, /personal_access_tokens/self und (wenn die Anmeldedaten kein persönlicher Zugriffstoken sind) /oauth/token/info. OAuth-Diagnosen melden Scopes und verbleibende Lebensdauer, legen aber niemals den Token oder die OAuth-Anwendungskennung offen. GitLab kann diese Endpunkte ausblenden oder weglassen, insbesondere bei älteren selbstverwalteten Versionen oder für Nicht-Administratoren, daher werden mehrdeutige Ergebnisse als unknown gemeldet und nicht geraten.

Jede Fähigkeit ist eine von available, unavailable, permission_required, license_required, not_configured oder unknown, mit einer prägnanten Begründung und unterstützenden Beweisen, wo sinnvoll. Übergeben Sie detailed: true für normalisierte Ergebnisse pro Probe oder refresh: true, um den Cache zu umgehen.

Ergebnisse werden 60 Sekunden pro normalisierter Instanz-URL und authentifizierter Anmeldedaten-Identität zwischengespeichert. Der Cache-Schlüssel enthält einen Einweg-SHA-256-Digest, niemals den rohen Bearer-Token. Einträge laufen nach 60 Sekunden ab, werden durch refresh umgangen und trennen natürlich Instanzen oder geänderte Anmeldedaten. Abgelaufene Einträge werden opportunistisch entfernt, und ein LRU-Limit von 256 Einträgen stellt eine harte Speichergrenze dar. Der Cache ist nur im Speicher und wird gelöscht, wenn der MCP-Serverprozess neu startet.

HTTP-Server

Für lokale Entwicklung:

$env:MCP_PUBLIC_URL = "https://mcp.example.com/mcp"
$env:GITLAB_URL = "https://gitlab.example.com"
npm.cmd run start:http

Der HTTP-Modus erfordert bei jeder /mcp-Anfrage einen Bearer-Token. Ein serverseitiger Token ist standardmäßig deaktiviert. ALLOW_SERVER_TOKEN_HTTP=true existiert nur für kontrollierte private Tests und sollte nicht für eine gemeinsame Bereitstellung verwendet werden.

Setzen Sie MCP_READ_ONLY=true für eine reine Inspektions-Bereitstellung. In diesem Modus registriert der Server nur Tools, die als schreibgeschützt annotiert sind, und bewirbt GitLabs read_api-OAuth-Scope. Der Standardmodus mit Schreibzugriff legt den vollständigen Tool-Satz offen und erfordert api. Der Server validiert jede Tool-Annotation während der Registrierung, sodass ein unklassifiziertes oder mutierendes Tool nicht stillschweigend in die schreibgeschützte Oberfläche gelangen kann.

Beim Binden an die IPv4-Wildcard 0.0.0.0 oder die IPv6-Wildcard :: setzen Sie MCP_ALLOWED_HOSTS auf eine durch Kommas getrennte Zulassungsliste öffentlicher Hostnamen. Platzieren Sie den Dienst hinter HTTPS und setzen Sie MCP_PUBLIC_URL auf seine kanonische öffentliche /mcp-URL. Der Produktionsmodus erfordert MCP_PUBLIC_URL, lehnt eingebettete Anmeldeinformationen, Abfragen, Fragmente und Nicht-/mcp-Pfade ab und erfordert HTTPS. MCP_ALLOW_INSECURE_PUBLIC_URL=true ist nur für die ausdrückliche lokale Entwicklung auf einem Loopback-Listener verfügbar und wird in der Produktion oder auf einem öffentlichen Host abgelehnt. ALLOW_SERVER_TOKEN_HTTP=true ist gleichermaßen auf Loopback-Privattests beschränkt und darf nicht für eine gemeinsame Bereitstellung verwendet werden.

Verwenden Sie nach der Installation oder Bereitstellung das schreibgeschützte Tool get_runtime_info, um die Kern-/Verteilungsversionen, den Bereitstellungsmodus, die Schreibschutzfilterung und den deterministischen SHA-256-Fingerabdruck des registrierten Tool-Inventars zu bestätigen.

HTTP-MCP-Anforderungsbodies sind standardmäßig auf 8 MiB begrenzt. Dies ermöglicht begrenzte Multi-Datei-Commits und andere legitime große Tool-Nutzlasten und verhindert gleichzeitig unbegrenzte Anforderungspufferung. Setzen Sie MCP_MAX_REQUEST_BYTES auf eine Ganzzahl von 65.536 bis 26.214.400 Byte, um einen anderen Bereitstellungsgrenzwert zu verwenden. Jeder Reverse-Proxy vor dem Server muss mindestens dieselbe Anforderungsgröße zulassen.

Langlaufende HTTP-Bereitstellungen begrenzen auch den Authentifizierungs- und Anforderungsstatus:

• MCP_TOKEN_CACHE_MAX_ENTRIES begrenzt validierte Bearer-Identitäten, Standard 256, mit einer TTL von 60 Sekunden und LRU-Verdrängung;

• MCP_AUTH_FAILURE_LIMIT begrenzt abgelehnte Token pro direkt verbundene Adresse innerhalb von MCP_AUTH_FAILURE_WINDOW_MS, Standard 20 Fehlversuche pro 60 Sekunden;

• MCP_AUTH_FAILURE_MAX_ENTRIES begrenzt den Zustand der Fehlerverfolgung, Standard 1.024;

• MCP_MAX_CONCURRENT_REQUESTS begrenzt aktive MCP-Anforderungen, Standard 32; und

• MCP_MAX_CONCURRENT_REQUESTS_PER_IDENTITY begrenzt Anforderungen für einen validierten GitLab-Benutzer, Standard 4.

Konfigurieren Sie ergänzende Raten- und Verbindungsgrenzen am TLS-Reverse-Proxy. Die Anwendung verwendet bewusst die direkte Peer-Adresse, anstatt standardmäßig weitergeleiteten Headern zu vertrauen. Daher sollten Client-IP-Grenzen auf Proxy-Ebene angewendet werden, bevor der Datenverkehr diesen Dienst erreicht.

Der nicht authentifizierte /health-Endpunkt ist eine topologiefreie Prozess-Liveness-Prüfung. /ready ist eine separate Readiness-Prüfung und gibt 503 zurück, wenn seine Abhängigkeitssonde nicht verfügbar ist. Jede Antwort enthält eine generierte X-Request-Id; interne MCP-Fehler protokollieren nur diese Kennung und den Fehlertyp. Einbettende Anwendungen können einen Beobachter für den Abschluss von Anforderungen für Metriken bereitstellen, ohne Bearer-Token oder Anforderungsnutzlasten zu erhalten.

Überprüfen Sie nach der Bereitstellung die Metadaten der öffentlichen Ressource und beide Health-Semantiken:

npm.cmd run check:mcp-deployment -- https://mcp.example.com/mcp

Sicherheitsmodell

• Tools deklarieren Lese-, Schreib- und destruktive Annotationen.

• create_commit unterstützt nur nicht-destruktive Dateiaktionen; Löschungen und erzwungene Commit-Aktualisierungen erfordern das separat annotierte Tool create_destructive_commit mit Feldern für die Nebenläufigkeitssicherheit.

• GitLab-Antworttexte, einschließlich der Job-Logs, der Artefakte und der API-Fehler, werden unter strengen Byte-Grenzen gestreamt und bleiben von Anforderungszeitüberschreitungen abgedeckt;

• API-Fehler werden normalisiert, ohne Anmeldeinformationen auszugeben;

• Die Fähigkeitserkennung schwärzt Fehlerbelege und liest niemals private CI-Variablen oder Mutations-Endpunkte;

• HTTP-Bearer-Token werden gegen die konfigurierte GitLab-Instanz validiert und über einen Einweg-Token-Hash in einem begrenzten TTL/LRU-Cache zwischengespeichert;

• Abgelehnte Anmeldeinformationen und gleichzeitige Anforderungen werden begrenzt, ohne Token oder private Identitätsdetails zu protokollieren;

• Der HTTP-Modus fordert nicht authentifizierte Anforderungen mit Metadaten geschützter Ressourcen heraus;

• HTTP-Tools deklarieren pro Tool OAuth- oder private Server-Token-Sicherheitsschemata sowie für Modelle sichtbare Reautorisierungs-Challenges; und

• Skills erfordern eine ausdrückliche Absicht für Merge, Genehmigung, Löschung, Diskussionsauflösung und CI-Zustandsänderungen.

Lizenz

MIT