CircleCI MCP Server

Der CircleCI MCP Server verbindet KI-Assistenten wie Claude Code, Cursor, VS Code oder Windsurf mit der CI/CD-Plattform CircleCI. Wer seine Builds und Tests über CircleCI laufen lässt, kann dem Assistenten damit Fragen stellen wie „Warum ist der letzte Lauf auf dem Branch main fehlgeschlagen?“, „Welche Tests sind in diesem Job durchgefallen?“ oder „Starte den Workflow noch einmal“, ohne in die Weboberfläche zu wechseln und Logs von Hand zu kopieren. Betrieben wird der Server von CircleCI selbst. Laut Dokumentation läuft er als gehosteter Dienst unter https://mcp.circleci.com/v1/mcp, lokal muss nichts installiert oder gewartet werden.

Was ist der CircleCI MCP Server?

MCP, das Model Context Protocol, ist ein offenes Protokoll, mit dem KI-Assistenten Werkzeuge externer Dienste aufrufen. Der gehostete CircleCI-Server stellt dafür eine bewusst überschaubare Sammlung von Werkzeugen bereit, die laut Dokumentation dazu dient, CI-Läufe zu beobachten und gezielt darauf zu reagieren. Dazu gehören das Auflisten und Abrufen von Läufen (list_runs, get_run), das Anzeigen von Workflows und Jobs, das Lesen von Job-Logs (get_job_logs), das Auflisten von Artefakten und Testergebnissen sowie das erneute Starten oder Abbrechen eines Workflows. Zusätzlich kann der Assistent Nutzungsdaten für die Organisation herunterladen.

Wofür ist er besonders nützlich?

Der größte Nutzen liegt in der Fehlersuche. Schlägt ein Build fehl, liest der Assistent die Logs der betroffenen Schritte selbst, ordnet den Fehler dem Code zu, den Sie gerade im Editor geöffnet haben, und schlägt eine Korrektur vor. Das spart den Weg durch Weboberfläche, Log-Ausgabe und Zwischenablage. Auch Fragen wie „Welche Läufe sind auf diesem Branch zuletzt grün gewesen?“ lassen sich in einem Satz beantworten. Gegenüber allgemeinen Git- oder Shell-Servern kennt dieser Server die Begriffe von CircleCI, also Pipelines, Workflows, Jobs und Tests, und liefert dadurch Antworten, die direkt zur eigenen Pipeline passen.

Gehosteter Server, CLI-MCP und der veraltete lokale Server

CircleCI unterscheidet laut Dokumentation zwei Varianten. Der gehostete Server konzentriert sich auf den Betrieb, also Fehleranalyse, Logs und Workflow-Steuerung. Der CLI-MCP ist in die CircleCI-CLI eingebaut, läuft lokal und deckt einen größeren Umfang ab, etwa das Schreiben von Konfigurationen, Orb-Werkzeuge und Richtlinienverwaltung. Das frühere npm-Paket @circleci/mcp-server-circleci ist dagegen veraltet: Das Repository trägt den Hinweis, dass es nicht mehr gepflegt wird und auf den gehosteten Server verweist. Entfernen Sie ältere Einrichtungen, bevor Sie den gehosteten Server verbinden.

Einrichtung

Für Claude Code nennt die Dokumentation den Befehl claude mcp add --transport http circleci-mcp-server https://mcp.circleci.com/v1/mcp. Claude Desktop, claude.ai und Cursor führen CircleCI in ihren Verzeichnissen, dort genügt es, den Eintrag hinzuzufügen und sich anzumelden. Für VS Code und Windsurf tragen Sie die URL in .vscode/mcp.json beziehungsweise mcp_config.json ein. Die Anmeldung erfolgt bevorzugt per OAuth2: Die meisten Clients erkennen das und öffnen beim ersten Verbinden die Anmeldung bei CircleCI. Kann ein Client keinen OAuth2-Ablauf durchführen, ist ein persönliches API-Token als Bearer-Header der Ausweichweg.

Sicherheit und Grenzen

Der Assistent handelt im Rahmen Ihres CircleCI-Kontos. Zwei der Werkzeuge, das erneute Starten und das Abbrechen von Workflows, verändern den Zustand Ihrer Pipelines; die Dokumentation empfiehlt, solche Aktionen auf gemeinsam genutzten Projekten vor der Bestätigung zu prüfen. Job-Logs können Zugangsdaten oder personenbezogene Daten enthalten und gelangen in den Kontext des KI-Clients und damit zum Modellanbieter. Bevorzugen Sie OAuth2 gegenüber langlebigen Tokens und legen Sie Tokens nie in Konfigurationsdateien ab, die in ein Repository gelangen.

Kosten

Laut Dokumentation steht der gehostete Server auf den Plänen Free, Performance und Scale zur Verfügung und unterstützt alle von CircleCI angebundenen Versionsverwaltungen. Ein Konto mit Zugriff auf die Projekte genügt. Welche Konditionen für Ihre Builds gelten, entnehmen Sie der offiziellen Preisseite von CircleCI.

Für wen lohnt sich der CircleCI MCP Server?

Er lohnt sich für Entwicklungsteams, die CircleCI bereits produktiv einsetzen und häufig Zeit mit fehlgeschlagenen Läufen verbringen. Wer eine andere CI-Plattform nutzt, hat davon keinen Nutzen, denn der Server ist ein Zugang zu CircleCI und kein eigenständiges Werkzeug.

Ein CircleCI-Konto mit Zugriff auf die Projekte und ein MCP-Client mit Unterstützung für Remote-Server über HTTP, etwa Claude Code, Cursor, VS Code oder Windsurf.

Mit dem CircleCI MCP Server untersucht ein KI-Assistent fehlgeschlagene Pipelines, liest Job-Logs und startet Workflows erneut. Dieser Ratgeber führt von der Einrichtung bis zur ersten Fehleranalyse.

Schritt 1: Voraussetzungen prüfen

Sie benötigen ein CircleCI-Konto mit Zugriff auf Ihre Projekte und einen MCP-Client, der Remote-Server über HTTP unterstützt. Laut Dokumentation steht der gehostete Server auf den Plänen Free, Performance und Scale bereit, lokal installieren müssen Sie nichts.

Alten lokalen Server entfernen

Das frühere Paket @circleci/mcp-server-circleci ist veraltet und wird nicht mehr gepflegt. Entfernen Sie einen vorhandenen Eintrag aus der MCP-Konfiguration Ihres Clients, bevor Sie den gehosteten Server verbinden, damit sich beide nicht überschneiden.

Schritt 2: In Claude Code einrichten

Fügen Sie den Server mit claude mcp add --transport http circleci-mcp-server https://mcp.circleci.com/v1/mcp hinzu. Beim ersten Verbinden öffnet sich die Anmeldung bei CircleCI; bestätigen Sie den Zugriff.

claude mcp add --transport http circleci-mcp-server https://mcp.circleci.com/v1/mcp

Andere Clients

Claude Desktop, claude.ai und Cursor führen CircleCI in ihren Verzeichnissen: Eintrag suchen, hinzufügen, anmelden. In VS Code tragen Sie die URL https://mcp.circleci.com/v1/mcp in .vscode/mcp.json ein, in Windsurf in mcp_config.json.

Schritt 3: Token als Ausweichweg

Kann Ihr Client keinen OAuth2-Ablauf durchführen, übergeben Sie ein persönliches API-Token als Header Authorization: Bearer <token>. Lesen Sie es aus einer Umgebungsvariablen und legen Sie es nicht in einer Datei ab, die in ein Repository gelangt.

Schritt 4: Erste Abfragen

Beginnen Sie mit der Verbindungsprüfung über das Werkzeug hello, danach lesend: „Zeige die letzten fehlgeschlagenen Läufe auf dem Branch main.“ oder „Lies die Logs des fehlgeschlagenen Jobs und erkläre die Ursache.“ Nennen Sie Branch oder Lauf möglichst genau.

Eingriffe bewusst bestätigen

Erneutes Starten und Abbrechen von Workflows verändert den Zustand Ihrer Pipelines. Prüfen Sie diese Aktionen auf gemeinsam genutzten Projekten, bevor Sie sie bestätigen. Beachten Sie außerdem, dass Logs in den Kontext des KI-Clients gelangen und Zugangsdaten enthalten können.

OAuth2 mit Anmeldung beim CircleCI-Konto (empfohlen) oder persönliches API-Token als Bearer-Header, wenn der Client keinen OAuth2-Ablauf unterstützt.

Zugriff auf Läufe, Workflows, Jobs, Logs, Artefakte, Testergebnisse und Nutzungsdaten der Projekte des Kontos sowie Steuerung von Workflows (erneut starten, abbrechen).

Der Server läuft gehostet bei CircleCI. Logs und Testergebnisse, die der Assistent abruft, gelangen in den Kontext des KI-Clients und damit zum Modellanbieter.

Versehentliches Abbrechen oder erneutes Starten von Workflows, Offenlegung von Logs mit Zugangsdaten oder personenbezogenen Daten gegenüber dem Modellanbieter und Missbrauch langlebiger API-Tokens.