gitlab-ci-mcp

MCP-Server für GitLab CI/CD. Ermöglicht es einem LLM-Agenten (Claude Code, Cursor, OpenCode, DevX Agent usw.), mit Pipelines, Jobs, Zeitplänen, Branches, Tags, Merge Requests und Repository-Dateien zu arbeiten.

Python, FastMCP, stdio-Transport.

Funktioniert mit jedem GitLab — SaaS gitlab.com oder selbst gehostet / on-prem. Entwickelt mit Blick auf Unternehmensnetzwerke: konfigurierbare NO_PROXY-Handhabung, optionaler SSL-Verifizierungs-Schalter, projektbezogene Eingrenzung über Umgebungsvariablen.

Design-Highlights

• Tool-Annotationen — jedes Tool enthält readOnlyHint / destructiveHint / idempotentHint / openWorldHint, damit MCP-Clients Operationen klassifizieren können (z. B. Bestätigung nur bei destruktiven Aktionen wie gitlab_merge_mr, gitlab_delete_schedule anfordern).

• Strukturierte Ausgabe bei jedem Tool — jedes Tool deklariert einen TypedDict-Rückgabetyp, sodass FastMCP automatisch ein outputSchema generiert und jedes Ergebnis neben einem vorgerenderten Markdown-Textblock auch structuredContent enthält. Clients, die strukturierte Daten rendern können, nutzen diese; Agenten, die kompakten Text bevorzugen, erhalten das Markdown. Kein response_format-Parameter erforderlich.

• Strukturierte Fehler — Authentifizierungs-, 404-, 403-, 429- (Rate-Limit), 5xx- und fehlende Umgebungsvariablen-Fehler werden in umsetzbare ToolError-Meldungen umgewandelt (z. B. "GitLab-Authentifizierung fehlgeschlagen… überprüfen Sie, ob GITLAB_TOKEN den api-Scope hat") und als isError=True-Ergebnisse ausgegeben.

• Pydantic-Eingabevalidierung — jedes Argument hat typisierte Einschränkungen (Bereiche, Längen, Literale), die automatisch als JSON-Schema offengelegt werden.

• Projekt-Scoping pro Aufruf — jedes Tool akzeptiert ein optionales project_path, das GITLAB_PROJECT_PATH für projektübergreifende Abfragen überschreibt.

• Paginierung — Listen-Tools geben einen pagination-Block mit page, total, has_more, next_page und einem Hinweis auf die nächste Seite in der Markdown-Fußzeile zurück.

• MCP-Kontext-Integration — gitlab_pipeline_health und gitlab_get_job_log sind async und senden info-Logs / report_progress-Ereignisse über den MCP-Kontext, damit Clients Fortschrittsbalken anzeigen können.

• MCP-Ressourcen — gitlab://project/info und gitlab://project/ci-config spiegeln gängige Abfragen für Clients wider, die das Ressourcenmodell gegenüber Tools bevorzugen.

• Lebenszyklus-Management — python-gitlab-HTTP-Sitzungen werden beim Herunterfahren des Servers sauber über einen asynccontextmanager-Lebenszyklus-Hook geschlossen.

• Log-Grep — gitlab_get_job_log akzeptiert grep_pattern + grep_context (umliegende Zeilen) für die Regex-Filterung von CI-Logs im Megabyte-Bereich, ohne den gesamten Trace in den Agenten-Kontext zu ziehen.

Threading-Modell

FastMCP führt synchrone Tools automatisch in einem Worker-Thread aus (anyio.to_thread.run_sync), sodass sie die asyncio-Ereignisschleife nicht blockieren — python-gitlab ist eine synchrone Bibliothek, und das manuelle Umhüllen jedes Aufrufs in asyncio.to_thread wäre zu aufwendig. Tools, die vom MCP-Kontext profitieren (Fortschritt, Info-Logs), sind als async def geschrieben und umhüllen python-gitlab-Aufrufe explizit mit asyncio.to_thread.

Funktionen

23 Tools, die den täglichen CI/CD-Umfang abdecken:

Pipelines gitlab_list_pipelines · gitlab_get_pipeline · gitlab_get_pipeline_jobs · gitlab_get_job_log · gitlab_trigger_pipeline · gitlab_retry_pipeline · gitlab_cancel_pipeline · gitlab_pipeline_health

Zeitpläne gitlab_list_schedules · gitlab_create_schedule · gitlab_update_schedule · gitlab_delete_schedule

Branches & Tags gitlab_list_branches · gitlab_list_tags · gitlab_compare_branches

Merge Requests gitlab_list_merge_requests · gitlab_get_merge_request · gitlab_get_merge_request_changes · gitlab_create_merge_request · gitlab_merge_mr

Repository & Projekt gitlab_get_file · gitlab_list_repository_tree · gitlab_project_info

Pipeline-Gesundheitsbericht

gitlab_pipeline_health gibt eine leicht lesbare Zusammenfassung über 7/30 Tage zurück:

Last 7d:  96.4%  up   | 27/28 success
Last 30d: 92.1%       | 105/114 success
Last 10:  success success success failed success ...

Praktisch für On-Call / Triage: покажи health master за последние 7 дней.

Installation

Erfordert Python 3.10+.

# via uvx (recommended)
uvx --from gitlab-ci-mcp gitlab-ci-mcp

# or via pip/pipx
pipx install gitlab-ci-mcp

Konfiguration

Die gesamte Konfiguration erfolgt über Umgebungsvariablen:

Jedes Tool akzeptiert ein optionales project_path-Argument, das GITLAB_PROJECT_PATH pro Aufruf überschreibt — nützlich für projektübergreifende Abfragen.

Claude Code

Vollständige Anleitung: docs/claude-code.md — Voraussetzungen, zwei Installationswege, Multi-Projekt-Setup, selbst gehostetes GitLab hinter einem Unternehmens-Proxy, Fehlerbehebung, Deinstallation.

Kurzfassung:

claude mcp add gitlab uvx --from gitlab-ci-mcp gitlab-ci-mcp \
  --env GITLAB_URL=https://gitlab.example.com \
  --env GITLAB_TOKEN=glpat-xxxxxx \
  --env GITLAB_PROJECT_PATH=my-org/my-repo

Oder in ~/.claude.json / Projekt .mcp.json:

{
  "mcpServers": {
    "gitlab": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "gitlab-ci-mcp", "gitlab-ci-mcp"],
      "env": {
        "GITLAB_URL": "https://gitlab.example.com",
        "GITLAB_TOKEN": "${GITLAB_TOKEN}",
        "GITLAB_PROJECT_PATH": "my-org/my-repo",
        "GITLAB_SSL_VERIFY": "true"
      }
    }
  }
}

Überprüfung:

claude mcp list
# gitlab: uvx --from gitlab-ci-mcp gitlab-ci-mcp - ✓ Connected

Cursor / OpenCode / DevX Agent

Das gleiche Prinzip — verweisen Sie die MCP-Konfiguration auf uvx --from gitlab-ci-mcp gitlab-ci-mcp mit den oben genannten Umgebungsvariablen. Siehe die MCP-Konfigurationssyntax des jeweiligen Tools.

Beispiel-Prompts

что сломалось в последнем pipeline master

покажи health master за 7 дней для проекта my-org/other-repo

создай MR из feature/foo в master с title "feat: foo"

покажи содержимое .gitlab-ci.yml из master

Rate Limits & Verbindungs-Wiederverwendung

GitLab erzwingt ein benutzerbezogenes Rate Limit (typischerweise 2000 Anfragen/h für die REST-API, konfigurierbar durch den Administrator — siehe /admin/application_settings/network Ihrer Instanz).

• Der Server speichert eine python-gitlab-HTTP-Sitzung pro project_path, sodass wiederholte Tool-Aufrufe für dasselbe Projekt die Verbindung wiederverwenden und sich nicht jedes Mal neu authentifizieren.

• Listen-Tools verwenden standardmäßig per_page=20, um einen einzelnen Aufruf innerhalb einer kleinen Anzahl von API-Anfragen zu halten.

• Wenn Sie ein 429 Too Many Requests erhalten, gibt der Fehler-Handler eine umsetzbare Meldung zurück — warten Sie und versuchen Sie es erneut mit einem größeren per_page-Wert oder weniger Aufrufen.

Selbst gehostetes GitLab hinter einem Unternehmens-Proxy

Wenn Ihr Laptop einen lokalen HTTP-Proxy hat (z. B. http://127.0.0.1:3128 für den Webzugriff im Unternehmen), GitLab sich aber im Intranet befindet, fängt der Proxy interne Anfragen ab und bricht sie ab. Zwei Optionen:

1. Setzen Sie GITLAB_NO_PROXY_DOMAINS — der Server fügt diese beim Start zu NO_PROXY hinzu und entfernt HTTP_PROXY/HTTPS_PROXY aus seinem eigenen Prozess, damit sie den GitLab-Datenverkehr nicht beeinflussen.

2. Übergeben Sie explizit leere HTTP_PROXY="" usw. im env-Abschnitt von MCP.

Entwicklung

git clone https://github.com/mshegolev/gitlab-ci-mcp
cd gitlab-ci-mcp
python -m venv .venv && . .venv/bin/activate
pip install -e '.[dev]'
pytest

Führen Sie den Server direkt aus (stdio-Transport, wartet auf stdin für MCP-Nachrichten):

GITLAB_URL=... GITLAB_TOKEN=... GITLAB_PROJECT_PATH=... gitlab-ci-mcp

Lizenz

MIT — siehe LICENSE.

Danksagungen

Aufgebaut auf python-gitlab und dem MCP Python SDK.