CircleCI

offiziell

Ermöglicht KI-Agenten, Build-Fehler von CircleCI zu beheben.

Was kann man mit CircleCI MCP machen?

  • CircleCI-Konfiguration validieren — Lassen Sie Ihre .circleci/config.yml auf Syntax- und Semantikfehler über config_helper prüfen.
  • Pipeline-Status abrufen — Überprüfen Sie den neuesten Pipeline-Status für einen Branch mit get_latest_pipeline_status.
  • Pipelines auslösen und erneut ausführen — Starten Sie eine neue Pipeline mit run_pipeline oder führen Sie einen Workflow von Anfang oder ab einem fehlgeschlagenen Job über rerun_workflow erneut aus.
  • Build-Fehler untersuchen — Rufen Sie detaillierte Fehlerprotokolle mit get_build_failure_logs und Testergebnisse über get_job_test_results ab.
  • Flaky Tests finden — Identifizieren Sie flaky Tests durch Analyse der Testausführungshistorie mit find_flaky_tests.
  • Nutzung und Kosten analysieren — Laden Sie Nutzungsdaten mit download_usage_api_data herunter und finden Sie untergenutzte Ressourcenklassen über find_underused_resource_classes.

Dokumentation

[!IMPORTANT] Dieses Paket ist veraltet. Bitte migrieren.

@circleci/mcp-server-circleci erhält keine neuen Funktionen mehr. Verwenden Sie stattdessen den gehosteten MCP-Server von CircleCI oder den CircleCI CLI MCP – siehe CircleCI MCP-Übersicht.

Dieses Repository wird archiviert. Bestehende Versionen bleiben über npm installierbar, aber der Betrieb eines ungewarteten Servers, der ein CircleCI-Personal-API-Token hält, wird nicht empfohlen.

Wenn Sie den selbstverwalteten Remote-Transport (start=remote) ausführen, migrieren Sie zuerst: Der gehostete Server ist der direkte Ersatz und macht den Betrieb eines netzwerkzugänglichen Dienstes überflüssig, der das Token Ihrer Organisation vermittelt.

CircleCI MCP Server

License: Apache 2.0 CircleCI npm

Model Context Protocol (MCP) ist ein neues, standardisiertes Protokoll zur Verwaltung von Kontext zwischen großen Sprachmodellen (LLMs) und externen Systemen. In diesem Repository stellen wir einen MCP-Server für CircleCI bereit.

Verwenden Sie Cursor, Windsurf, Copilot, Claude oder einen beliebigen MCP-kompatiblen Client, um mit CircleCI in natürlicher Sprache zu interagieren – ohne Ihre IDE zu verlassen.

Tools

ToolBeschreibung
config_helperValidieren und erhalten Sie Anleitungen für Ihre CircleCI-Konfiguration
download_usage_api_dataLaden Sie Nutzungsdaten von der CircleCI Usage API herunter
find_flaky_testsIdentifizieren Sie flaky Tests durch Analyse der Testausführungshistorie
find_underused_resource_classesFinden Sie Jobs mit ungenutzten Rechenressourcen
get_build_failure_logsRufen Sie detaillierte Fehlerprotokolle von CircleCI-Builds ab
get_job_test_resultsRufen Sie Testmetadaten und -ergebnisse für CircleCI-Jobs ab
get_latest_pipeline_statusErhalten Sie den Status der neuesten Pipeline für einen Branch
list_artifactsListen Sie Artefakte auf, die von einem CircleCI-Job erzeugt wurden
list_component_versionsListen Sie alle Versionen für eine CircleCI-Komponente auf
list_followed_projectsListen Sie alle CircleCI-Projekte auf, denen Sie folgen
rerun_workflowFühren Sie einen Workflow von Anfang oder vom fehlgeschlagenen Job erneut aus
run_pipelineLösen Sie eine Pipeline aus
run_rollback_pipelineLösen Sie ein Rollback für ein Projekt aus

Installation

Team / zentrale Bereitstellung: Um einen gemeinsamen Remote-Server für Ihre Organisation (Kubernetes, Docker usw.) mit pro-Entwickler- oder gemeinsamen CircleCI-Tokens auszuführen, siehe Self-Managed Remote MCP Server.

Cursor

Voraussetzungen:

Verwenden von NPX in einem lokalen MCP-Server

Fügen Sie Folgendes zu Ihrer Cursor-MCP-Konfiguration hinzu:

{
  "mcpServers": {
    "circleci-mcp-server": {
      "command": "npx",
      "args": ["-y", "@circleci/mcp-server-circleci@latest"],
      "env": {
        "CIRCLECI_TOKEN": "your-circleci-token",
        "CIRCLECI_BASE_URL": "https://circleci.com",
        "MAX_MCP_OUTPUT_LENGTH": "50000"
      }
    }
  }
}

CIRCLECI_BASE_URL ist optional – nur für On-Premises-Kunden erforderlich. MAX_MCP_OUTPUT_LENGTH ist optional – maximale Ausgabelänge für MCP-Antworten (Standard: 50000).

Verwenden von Docker in einem lokalen MCP-Server

Fügen Sie Folgendes zu Ihrer Cursor-MCP-Konfiguration hinzu:

{
  "mcpServers": {
    "circleci-mcp-server": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "CIRCLECI_TOKEN",
        "-e",
        "CIRCLECI_BASE_URL",
        "-e",
        "MAX_MCP_OUTPUT_LENGTH",
        "circleci/mcp-server-circleci"
      ],
      "env": {
        "CIRCLECI_TOKEN": "your-circleci-token",
        "CIRCLECI_BASE_URL": "https://circleci.com",
        "MAX_MCP_OUTPUT_LENGTH": "50000"
      }
    }
  }
}

Verwenden eines selbstverwalteten Remote-MCP-Servers

Siehe Self-Managed Remote MCP Server. Verwenden Sie die pro-Benutzer-Client-Konfiguration und fügen Sie sie zu Ihrer Cursor-MCP-Konfiguration hinzu (Cursor Settings → MCP).

VS Code

Voraussetzungen:

Verwenden von NPX in einem lokalen MCP-Server

Fügen Sie Folgendes zu .vscode/mcp.json in Ihrem Projekt hinzu:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "circleci-token",
      "description": "CircleCI API Token",
      "password": true
    },
    {
      "type": "promptString",
      "id": "circleci-base-url",
      "description": "CircleCI Base URL",
      "default": "https://circleci.com"
    }
  ],
  "servers": {
    "circleci-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@circleci/mcp-server-circleci@latest"],
      "env": {
        "CIRCLECI_TOKEN": "${input:circleci-token}",
        "CIRCLECI_BASE_URL": "${input:circleci-base-url}"
      }
    }
  }
}

💡 Eingaben werden beim ersten Serverstart abgefragt und dann sicher von VS Code gespeichert.

Verwenden von Docker in einem lokalen MCP-Server

Fügen Sie Folgendes zu .vscode/mcp.json in Ihrem Projekt hinzu:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "circleci-token",
      "description": "CircleCI API Token",
      "password": true
    },
    {
      "type": "promptString",
      "id": "circleci-base-url",
      "description": "CircleCI Base URL",
      "default": "https://circleci.com"
    }
  ],
  "servers": {
    "circleci-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "CIRCLECI_TOKEN",
        "-e",
        "CIRCLECI_BASE_URL",
        "circleci/mcp-server-circleci"
      ],
      "env": {
        "CIRCLECI_TOKEN": "${input:circleci-token}",
        "CIRCLECI_BASE_URL": "${input:circleci-base-url}"
      }
    }
  }
}

Verwenden eines selbstverwalteten Remote-MCP-Servers

Siehe Self-Managed Remote MCP Server. Verwenden Sie die pro-Benutzer-Client-Konfiguration in .vscode/mcp.json.

Claude Desktop

Voraussetzungen:

Verwenden von NPX in einem lokalen MCP-Server

Fügen Sie Folgendes zu Ihrer claude_desktop_config.json hinzu:

{
  "mcpServers": {
    "circleci-mcp-server": {
      "command": "npx",
      "args": ["-y", "@circleci/mcp-server-circleci@latest"],
      "env": {
        "CIRCLECI_TOKEN": "your-circleci-token",
        "CIRCLECI_BASE_URL": "https://circleci.com",
        "MAX_MCP_OUTPUT_LENGTH": "50000"
      }
    }
  }
}

Verwenden von Docker in einem lokalen MCP-Server

Fügen Sie Folgendes zu Ihrer claude_desktop_config.json hinzu:

{
  "mcpServers": {
    "circleci-mcp-server": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "CIRCLECI_TOKEN",
        "-e",
        "CIRCLECI_BASE_URL",
        "-e",
        "MAX_MCP_OUTPUT_LENGTH",
        "circleci/mcp-server-circleci"
      ],
      "env": {
        "CIRCLECI_TOKEN": "your-circleci-token",
        "CIRCLECI_BASE_URL": "https://circleci.com",
        "MAX_MCP_OUTPUT_LENGTH": "50000"
      }
    }
  }
}

Verwenden eines selbstverwalteten Remote-MCP-Servers

Siehe Self-Managed Remote MCP Server. Erstellen Sie ein Wrapper-Skript wie in Claude Desktop und CLI-Clients gezeigt, und richten Sie dann Ihre claude_desktop_config.json darauf aus.

Um Ihre Konfigurationsdatei zu finden oder zu erstellen, öffnen Sie die Claude-Desktop-Einstellungen, klicken Sie in der linken Seitenleiste auf Entwickler und dann auf Konfiguration bearbeiten. Die Konfigurationsdatei befindet sich unter:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json

Weitere Informationen: https://modelcontextprotocol.io/quickstart/user

Claude Code

Voraussetzungen:

Verwenden von NPX in einem lokalen MCP-Server

claude mcp add circleci-mcp-server -e CIRCLECI_TOKEN=your-circleci-token -- npx -y @circleci/mcp-server-circleci@latest

Verwenden von Docker in einem lokalen MCP-Server

claude mcp add circleci-mcp-server -e CIRCLECI_TOKEN=your-circleci-token -e CIRCLECI_BASE_URL=https://circleci.com -- docker run --rm -i -e CIRCLECI_TOKEN -e CIRCLECI_BASE_URL circleci/mcp-server-circleci

Verwenden eines selbstverwalteten Remote-MCP-Servers

Siehe Self-Managed Remote MCP Server und die dortige Claude Code-Client-Einrichtung.

Windsurf

Voraussetzungen:

Verwenden von NPX in einem lokalen MCP-Server

Fügen Sie Folgendes zu Ihrer Windsurf-mcp_config.json hinzu:

{
  "mcpServers": {
    "circleci-mcp-server": {
      "command": "npx",
      "args": ["-y", "@circleci/mcp-server-circleci@latest"],
      "env": {
        "CIRCLECI_TOKEN": "your-circleci-token",
        "CIRCLECI_BASE_URL": "https://circleci.com",
        "MAX_MCP_OUTPUT_LENGTH": "50000"
      }
    }
  }
}

Verwenden von Docker in einem lokalen MCP-Server

Fügen Sie Folgendes zu Ihrer Windsurf-mcp_config.json hinzu:

{
  "mcpServers": {
    "circleci-mcp-server": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "CIRCLECI_TOKEN",
        "-e",
        "CIRCLECI_BASE_URL",
        "-e",
        "MAX_MCP_OUTPUT_LENGTH",
        "circleci/mcp-server-circleci"
      ],
      "env": {
        "CIRCLECI_TOKEN": "your-circleci-token",
        "CIRCLECI_BASE_URL": "https://circleci.com",
        "MAX_MCP_OUTPUT_LENGTH": "50000"
      }
    }
  }
}

Verwenden eines selbstverwalteten Remote-MCP-Servers

Siehe Self-Managed Remote MCP Server. Verwenden Sie die pro-Benutzer-Client-Konfiguration in Ihrer Windsurf-mcp_config.json.

Weitere Informationen: https://docs.windsurf.com/windsurf/mcp

Amazon Q Developer CLI

Voraussetzungen:

Die MCP-Client-Konfiguration in Amazon Q Developer wird im JSON-Format in einer Datei namens mcp.json gespeichert. Es werden zwei Konfigurationsebenen unterstützt:

  • Global: ~/.aws/amazonq/mcp.json – gilt für alle Arbeitsbereiche
  • Arbeitsbereich: .amazonq/mcp.json – spezifisch für den aktuellen Arbeitsbereich

Wenn beide Dateien vorhanden sind, werden ihre Inhalte zusammengeführt. Bei Konflikten hat die Arbeitsbereichskonfiguration Vorrang.

Verwenden von NPX in einem lokalen MCP-Server

Bearbeiten Sie ~/.aws/amazonq/mcp.json oder erstellen Sie .amazonq/mcp.json mit Folgendem:

{
  "mcpServers": {
    "circleci-local": {
      "command": "npx",
      "args": [
        "-y",
        "@circleci/mcp-server-circleci@latest"
      ],
      "env": {
        "CIRCLECI_TOKEN": "YOUR_CIRCLECI_TOKEN",
        "CIRCLECI_BASE_URL": "https://circleci.com",
        "MAX_MCP_OUTPUT_LENGTH": "50000"
      },
      "timeout": 60000
    }
  }
}

Verwenden eines selbstverwalteten Remote-MCP-Servers

Siehe Self-Managed Remote MCP Server. Verwenden Sie ein Wrapper-Skript wie in Claude Desktop und CLI-Clients gezeigt, und registrieren Sie es dann mit q mcp add.

Amazon Q Developer in der IDE

Voraussetzungen:

Verwenden von NPX in einem lokalen MCP-Server

Bearbeiten Sie ~/.aws/amazonq/mcp.json oder erstellen Sie .amazonq/mcp.json mit Folgendem:

{
  "mcpServers": {
    "circleci-local": {
      "command": "npx",
      "args": [
        "-y",
        "@circleci/mcp-server-circleci@latest"
      ],
      "env": {
        "CIRCLECI_TOKEN": "YOUR_CIRCLECI_TOKEN",
        "CIRCLECI_BASE_URL": "https://circleci.com",
        "MAX_MCP_OUTPUT_LENGTH": "50000"
      },
      "timeout": 60000
    }
  }
}

Verwenden eines selbstverwalteten Remote-MCP-Servers

Siehe Self-Managed Remote MCP Server. Verwenden Sie ein Wrapper-Skript wie in Claude Desktop und CLI-Clients gezeigt, und fügen Sie es dann über die MCP-Konfigurationsoberfläche hinzu:

  1. Rufen Sie die MCP-Konfigurationsoberfläche auf
  2. Wählen Sie das Symbol +
  3. Wählen Sie den Bereich: global oder lokal
  4. Geben Sie einen Namen ein (z. B. circleci-remote-mcp)
  5. Wählen Sie das Transportprotokoll: stdio
  6. Geben Sie den Befehlspfad zu Ihrem Skript ein
  7. Klicken Sie auf Speichern
Smithery

Um den CircleCI-MCP-Server für Claude Desktop automatisch über Smithery zu installieren:

npx -y @smithery/cli install @CircleCI-Public/mcp-server-circleci --client claude

Selbstverwalteter Remote-MCP-Server

Führen Sie den MCP-Server zentral aus (z. B. auf Kubernetes oder Docker), damit Ihr Team eine gemeinsame Bereitstellung nutzt. Wählen Sie, wie sich Entwickler authentifizieren:

Wählen Sie einen Bereitstellungsmodus

ModusWann verwendenServer-EinrichtungClient-EinrichtungCircleCI-Überwachungspfad
Pro-Benutzer-Tokens (empfohlen)Teams mit SSO-gestützten Personal-API-TokensREQUIRE_REQUEST_TOKEN=true, kein Server-PATJeder Entwickler leitet sein PAT weiterPro Entwickler
Gemeinsames Token (interim)Schnelle Einführung, einzelne Dienstidentität OKCIRCLECI_TOKEN auf dem Server, REQUIRE_REQUEST_TOKEN=false (expliziter Opt-out)Kein Auth-Header erforderlichEinzelne gemeinsame Identität

Sicherheit: Die Anforderungsauthentifizierung ist im Remote-Modus standardmäßig aktiviert. Der Shared-Token-Modus deaktiviert sie (REQUIRE_REQUEST_TOKEN=false), sodass jeder Aufrufer ohne Anmeldeinformationen als die CIRCLECI_TOKEN-Identität des Servers handeln kann – einschließlich des Auslösens von Pipelines mit beliebiger Konfiguration. Aktivieren Sie ihn nur in einem Netzwerk, dem Sie vollständig vertrauen, und bevorzugen Sie andernfalls Pro-Benutzer-Tokens. Die Beendigung von TLS an einem Ingress bietet Verschlüsselung, aber keine Authentifizierung.

Da diese Kombination auf einer öffentlichen Schnittstelle unsicher ist, weigert sich der Server zu starten, wenn REQUIRE_REQUEST_TOKEN=false mit einer Nicht-Loopback-Bind-Adresse kombiniert wird, es sei denn, Sie akzeptieren das Risiko explizit mit MCP_ALLOW_UNAUTHENTICATED_NETWORK_ACCESS=true. Die Host/Origin-Prüfung ist kein Ersatz für Authentifizierung – siehe DNS-Rebinding-Schutz unten.

1. Server bereitstellen

Beide Modi verwenden den Remote-HTTP-Modus (start=remote). Veröffentlichen Sie Port 8000 (oder Ihren gewählten Port).

Pro-Benutzer-Tokens (empfohlen) – Zugriff über mcp-remote von localhost aus:

docker run --rm -p 8000:8000 \
  -e start=remote \
  -e port=8000 \
  -e REQUIRE_REQUEST_TOKEN=true \
  circleci/mcp-server-circleci

Pro-Benutzer-Tokens (empfohlen) – Zugriff über mcp-remote von einem öffentlichen Hostnamen aus:

docker run --rm -p 8000:8000 \
  -e start=remote \
  -e port=8000 \
  -e REQUIRE_REQUEST_TOKEN=true \
  -e MCP_ALLOWED_HOSTS=my-mcp.example.com \
  circleci/mcp-server-circleci

Gemeinsames Token (interim) – Zugriff über mcp-remote von einem öffentlichen Hostnamen aus:

Da dieser Modus das PAT der Organisation jedem Aufrufer ohne Anmeldeinformationen bereitstellt, darf er nur dort ausgeführt werden, wo der veröffentlichte Port aus nicht vertrauenswürdigen Netzwerken nicht erreichbar ist, und Sie müssen dies explizit bestätigen, sonst weigert sich der Server zu starten:

docker run --rm -p 8000:8000 \
  -e start=remote \
  -e port=8000 \
  -e CIRCLECI_TOKEN=your-shared-circleci-pat \
  -e REQUIRE_REQUEST_TOKEN=false \
  -e MCP_ALLOW_UNAUTHENTICATED_NETWORK_ACCESS=true \
  -e MCP_ALLOWED_HOSTS=my-mcp.example.com \
  circleci/mcp-server-circleci

Bevorzugen Sie stattdessen die Authentifizierung vor dem Port – einen Ingress, der SSO, mTLS oder einen API-Schlüssel erfordert – oder wechseln Sie zu den oben genannten Pro-Benutzer-Tokens.

Umgebungsvariablen:

VariableBeschreibung
start=remoteStartet den HTTP+SSE-MCP-Server anstelle von stdio
portLauschender Port im Container (Standard: 8000)
REQUIRE_REQUEST_TOKENAnfragen ohne Authorization: Bearer- oder Circle-Token-Header ablehnen. Standardmäßig erforderlich; setzen Sie REQUIRE_REQUEST_TOKEN=false, um nicht authentifizierte Anfragen zuzulassen (Shared-Token-Modus)
CIRCLECI_TOKENGemeinsames Fallback-PAT für alle Anfragen, wenn keine benutzerspezifischen Header gesendet werden
CIRCLECI_BASE_URLOptional – nur für On-Premises erforderlich (Standard: https://circleci.com)
DISABLE_TELEMETRY=trueDeaktiviert den Export von Nutzungsmetriken
MCP_ALLOWED_HOSTSKommagetrennte Liste zusätzlicher Host-Headerwerte, die erlaubt sind (z. B. my-mcp.example.com,my-mcp.example.com:443). Loopback-Hostnamen sind immer erlaubt. Für jede Nicht-Loopback-Bereitstellung erforderlich.
MCP_ALLOWED_ORIGINSKommagetrennte Liste zusätzlicher Origin-Headerwerte, die erlaubt sind (z. B. https://my-app.example.com). Loopback-Ursprünge sind immer erlaubt. Nur erforderlich, wenn ein Browser diesen Server direkt erreicht (nicht über mcp-remote).
MCP_BIND_HOSTNetzwerk-Schnittstelle, an die gebunden wird (Standard: 0.0.0.0). Setzen Sie 127.0.0.1, um nur auf Loopback zu beschränken (nicht kompatibel mit Docker--p-Portzuordnung).
MCP_ALLOW_UNAUTHENTICATED_NETWORK_ACCESSErforderlich (=true), um mit REQUIRE_REQUEST_TOKEN=false auf einer Nicht-Loopback-Bind-Adresse zu starten. Bestätigt, dass jeder Peer, der den Port erreichen kann, ohne Berechtigungsnachweis als Server-CIRCLECI_TOKEN-Identität handelt. Hat keine Wirkung, wenn Anforderungstokens erforderlich sind.
MCP_FILE_OUTPUT_ROOTSKommagetrennte Liste zusätzlicher Verzeichnisse, die Datei-Lese-/Schreib-Tools verwenden dürfen (z. B. /srv/reports,/data/exports). Das Arbeitsverzeichnis, das Home-Verzeichnis und das Temp-Verzeichnis sind immer erlaubt. Siehe Hinweis unten.

Dateiausgabeorte (gilt für stdio- und Remote-Transports): Tools, die einen Dateisystempfad akzeptieren – get_build_failure_logs (outputDir), download_usage_api_data (outputDir) und find_underused_resource_classes (csvFilePath) – dürfen nur innerhalb des Arbeitsverzeichnisses des Servers, des Home-Verzeichnisses des Benutzers und des System-Temp-Verzeichnisses lesen und schreiben. Innerhalb dieser Wurzeln werden versteckte Konfigurationsverzeichnisse (~/.ssh, ~/.aws, ~/.config, .git, …), node_modules und Launch-Agent-Verzeichnisse abgelehnt, ebenso wie Symlinks, die außerhalb der erlaubten Wurzeln auflösen. Systemverzeichnisse (/etc, /usr, /bin, /System, /Library, %SystemRoot%, …) werden bedingungslos verweigert und können nicht wieder aktiviert werden. Ausgabedateien werden niemals über einen Symlink geschrieben.

Wenn sich Ihr Checkout außerhalb dieser Wurzeln befindet – /workspace in einem Container, /srv, /opt, ein sekundäres Volume wie /Volumes/work – setzen Sie MCP_FILE_OUTPUT_ROOTS auf dieses Verzeichnis, andernfalls werden diese Pfade abgelehnt. Bei einem stdio-Server ist das Arbeitsverzeichnis normalerweise bereits das Projektstammverzeichnis, sodass keine Konfiguration erforderlich ist. Dies ist am wichtigsten für den Remote-Transport, bei dem die Pfade von Netzwerk-Clients und nicht vom lokalen Benutzer stammen.

DNS-Rebinding-Schutz (keine Authentifizierung): Der Remote-Transport validiert den Host-Header bei jeder /mcp-Anforderung. Standardmäßig werden nur Loopback-Adressen (localhost, 127.0.0.1, [::1]) akzeptiert. Öffentliche Bereitstellungen müssen MCP_ALLOWED_HOSTS auf den Hostnamen setzen, den Clients verwenden, andernfalls erhalten alle /mcp-Anforderungen 403 Forbidden. Der /ping-Health-Check-Endpunkt ist nicht geschützt, sodass Load-Balancer-Probes unabhängig von Host weiterhin funktionieren.

Der Origin-Header (von Browsern gesendet) wird ebenfalls validiert, wenn er vorhanden ist. Nicht-Browser-Clients wie mcp-remote senden nie Origin, sodass diese von dieser Prüfung nicht betroffen sind.

Diese Prüfung ist keine Zugriffskontrolle und darf nicht als solche verwendet werden. Beide Header werden vom Aufrufer gewählt, sodass jeder Nicht-Browser-Client – curl, ein Skript, ein roher Socket – einen erlaubten Host senden und Origin weglassen kann, um sie zu erfüllen. Ihr einziger Zweck ist es, zu verhindern, dass ein Browser durch angreiferkontrolliertes DNS auf den Server gerichtet wird, was die DNS-Rebinding-Bedrohung darstellt. Die Authentifizierung von Aufrufern ist Aufgabe von REQUIRE_REQUEST_TOKEN (oder eines authentifizierenden Proxys vor dem Port). Die Anforderung eines Origin-Headers würde jeden legitimen CLI-Client brechen, während kein Angreifer gestoppt wird.

Hinter einem Reverse-Proxy: Wenn Ihr Proxy Host auf die Backend-Adresse umschreibt (Standard bei nginx), fügen Sie proxy_set_header Host $host; hinzu, um den ursprünglichen Hostnamen durchzureichen, und setzen Sie dann MCP_ALLOWED_HOSTS auf diesen öffentlichen Hostnamen. Alternativ setzen Sie MCP_ALLOWED_HOSTS auf den Hostnamen, den der Proxy tatsächlich weiterleitet.

Der Server akzeptiert Pro-Anfrage-Tokens über:

  • Authorization: Bearer <circleci-pat>
  • Circle-Token: <circleci-pat>

Wenn ein Client einen Header-Token sendet, hat dieser Vorrang vor CIRCLECI_TOKEN auf dem Server.

Telemetriemetriken, die während einer Anfrage erfasst werden, werden mit demselben Token wie diese Anfrage exportiert.

2. Clients konfigurieren

Die meisten MCP-Clients unterstützen nur lokale (stdio-)Prozesse. Verwenden Sie mcp-remote, eine Drittanbieter-stdio-zu-HTTP-Brücke, um sie mit Ihrem Remote-Server zu verbinden.

URL-Schema: Verwenden Sie http://localhost:8000/mcp mit --allow-http für lokale Tests. In Produktion beenden Sie TLS an Ihrem Ingress/Load-Balancer und verwenden Sie https://your-host/mcp ohne --allow-http.

Windows: Vermeiden Sie Leerzeichen um den Doppelpunkt in --header-Werten. Platzieren Sie den vollständigen Bearer <token>-Wert in einer Umgebungsvariablen.

Sicherheit: Die Beispiele verwenden npx der Einfachheit halber. Verwenden Sie für Produktions- oder Team-Rollouts eine bestimmte Version in Ihrer MCP-Konfiguration (z. B. mcp-remote@0.1.38 statt mcp-remote). Verwenden Sie keine Versionen unter 0.1.16 (CVE-2025-6514).

Clientkonfiguration: Pro-Benutzer-Tokens

Jeder Entwickler leitet sein eigenes CircleCI-Personal-API-Token bei jeder Anfrage weiter:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "circleci-token",
      "description": "CircleCI API Token",
      "password": true
    }
  ],
  "mcpServers": {
    "circleci-mcp-server-remote": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://localhost:8000/mcp",
        "--allow-http",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer ${input:circleci-token}"
      }
    }
  }
}

Ersetzen Sie http://localhost:8000/mcp durch die Server-URL Ihres Teams. Cursor und VS Code unterstützen ${input:...}-Eingabeaufforderungen; andere Clients können AUTH_HEADER direkt festlegen.

Clientkonfiguration: Gemeinsames Token

Wenn der Server CIRCLECI_TOKEN gesetzt hat und mit REQUIRE_REQUEST_TOKEN=false gestartet wird (Anfrage-Authentifizierung ist standardmäßig aktiviert und muss explizit deaktiviert werden, und ein Nicht-Loopback-Bind erfordert zusätzlich MCP_ALLOW_UNAUTHENTICATED_NETWORK_ACCESS=true), müssen Clients kein Token senden:

{
  "mcpServers": {
    "circleci-mcp-server-remote": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://localhost:8000/mcp",
        "--allow-http"
      ]
    }
  }
}

Claude Desktop und CLI-Clients

Erstellen Sie ein Wrapper-Skript (z. B. circleci-remote-mcp.sh):

#!/bin/bash
export AUTH_HEADER="Bearer your-circleci-token"
npx mcp-remote http://localhost:8000/mcp --allow-http --header "Authorization:${AUTH_HEADER}"

Machen Sie es ausführbar (chmod +x circleci-remote-mcp.sh) und referenzieren Sie es dann in Ihrer MCP-Konfiguration:

{
  "mcpServers": {
    "circleci-remote-mcp-server": {
      "command": "/full/path/to/circleci-remote-mcp.sh"
    }
  }
}

Claude Code

claude mcp add circleci-mcp-server \
  -e AUTH_HEADER="Bearer your-circleci-token" \
  -- npx mcp-remote http://localhost:8000/mcp --allow-http --header "Authorization:${AUTH_HEADER}"

Lassen Sie --header und AUTH_HEADER weg, wenn Sie einen Shared-Token-Server verwenden.

3. Bereitstellung überprüfen

# Health check (no auth required)
curl http://localhost:8000/ping

# Should return 401 when REQUIRE_REQUEST_TOKEN=true and no token is sent
curl -s -o /dev/null -w "%{http_code}\n" -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'

# Should return 200 with a valid Bearer token and MCP Accept headers
curl -s -o /dev/null -w "%{http_code}\n" -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer your-circleci-pat" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'

Demo

In Aktion ansehen

Beispiel: „Finden Sie die neueste fehlgeschlagene Pipeline in meinem Branch und holen Sie Logs“ – siehe Wiki für weitere Beispiele.

https://github.com/user-attachments/assets/3c765985-8827-442a-a8dc-5069e01edb74

Tool-Details

config_helper

Unterstützt CircleCI-Konfigurationsaufgaben durch Anleitung und Validierung.

  • Validiert Ihre .circleci/config.yml auf Syntax- und Semantikfehler
  • Bietet detaillierte Validierungsergebnisse und Konfigurationsempfehlungen
  • Beispiel: „Validiere meine CircleCI-Konfiguration“
download_usage_api_data

Lädt Nutzungsdaten von der CircleCI-Usage-API für eine bestimmte Organisation herunter. Akzeptiert flexible Datumseingaben (z. B. „März 2025“ oder „letzten Monat“). Nur für Cloud verfügbar.

Option 1: Starten Sie einen neuen Exportjob, indem Sie Folgendes angeben:

  • orgId, startDate, endDate (max. 32 Tage), outputDir

Option 2: Prüfen/Herunterladen eines vorhandenen Exportjobs, indem Sie Folgendes angeben:

  • orgId, jobId, outputDir

Gibt eine CSV-Datei mit CircleCI-Nutzungsdaten für den angegebenen Zeitraum zurück.

[!NOTE] Nutzungsdaten können in das find_underused_resource_classes-Tool für Kostenoptimierungsanalysen eingespeist werden.

find_flaky_tests

Identifiziert flaky Tests in Ihrem CircleCI-Projekt durch Analyse der Testausführungshistorie. Nutzt die Flaky-Test-Erkennungsfunktion in CircleCI.

Dieses Tool kann auf drei Arten verwendet werden:

  1. Mit Projekt-Slug (empfohlen):

    • Verwenden Sie zuerst list_followed_projects, um Ihre Projekte zu erhalten, dann:
    • Beispiel: „Flaky-Tests für mein Projekt abrufen“
  2. Mit CircleCI-Projekt-URL:

  3. Mit lokalem Projektkontext:

    • Funktioniert aus Ihrem lokalen Arbeitsbereich, indem Sie Arbeitsbereichsstamm und git-Remote-URL angeben
    • Beispiel: „Flaky-Tests in meinem aktuellen Projekt finden“

Ausgabemodi:

  • Text (Standard): Gibt flaky Testdetails im Textformat zurück
  • Datei (erfordert FILE_OUTPUT_DIRECTORY env var): Erstellt ein Verzeichnis mit flaky Testdetails
find_underused_resource_classes

Analysiert eine CircleCI-Nutzungsdaten-CSV-Datei, um Jobs mit durchschnittlicher oder maximaler CPU-/RAM-Nutzung unter einem bestimmten Schwellenwert (Standard: 40 %) zu finden.

Geben Sie eine CSV-Datei an, die Sie von download_usage_api_data erhalten haben.

Gibt eine Markdown-Liste unterausgelasteter Jobs zurück, gruppiert nach Projekt und Workflow – nützlich zur Identifizierung von Kostensenkungsmöglichkeiten.

get_build_failure_logs

Ruft detaillierte Fehlerprotokolle von CircleCI-Builds ab. Dieses Tool kann auf drei Arten verwendet werden:

  1. Mit Projekt-Slug und Branch (empfohlen):

    • Verwenden Sie zuerst list_followed_projects, um Ihre Projekte zu erhalten, dann:
    • Beispiel: „Build-Fehler für mein Projekt im Haupt-Branch abrufen“
  2. Mit CircleCI-URLs:

  3. Mit lokalem Projektkontext:

    • Funktioniert aus Ihrem lokalen Arbeitsbereich, indem Sie Arbeitsbereichsstamm, git-Remote-URL und Branch-Namen angeben
    • Beispiel: „Die neueste fehlgeschlagene Pipeline in meinem aktuellen Branch finden“

Das Tool gibt formatierte Protokolle zurück, einschließlich:

  • Jobnamen
  • Schritt-für-Schritt-Ausführungsdetails
  • Fehlermeldungen und Kontext
get_job_test_results

Ruft Testmetadaten für CircleCI-Jobs ab, sodass Sie Testergebnisse ohne Verlassen Ihrer IDE analysieren können. Dieses Tool kann auf drei Arten verwendet werden:

  1. Mit Projekt-Slug und Branch (empfohlen):

    • Beispiel: „Testergebnisse für mein Projekt im Haupt-Branch abrufen“
  2. Mit CircleCI-URL:

    • Job-URL: https://app.circleci.com/pipelines/github/org/repo/123/workflows/abc-def/jobs/789
    • Workflow-URL: https://app.circleci.com/pipelines/github/org/repo/123/workflows/abc-def
    • Pipeline-URL: https://app.circleci.com/pipelines/github/org/repo/123
  3. Mit lokalem Projektkontext:

    • Funktioniert aus Ihrem lokalen Arbeitsbereich, indem Sie Arbeitsbereichsstamm, git-Remote-URL und Branch-Namen angeben

Das Tool gibt zurück:

  • Zusammenfassung aller Tests (gesamt, erfolgreich, fehlgeschlagen)
  • Detaillierte Informationen zu fehlgeschlagenen Tests: Name, Klasse, Datei, Fehlermeldung, Dauer
  • Liste erfolgreicher Tests mit Zeitangabe
  • Filter nach Testergebnis

[!NOTE] Testmetadaten müssen in Ihrer CircleCI-Konfiguration konfiguriert sein. Siehe Testdaten sammeln für Einrichtungsanweisungen.

get_latest_pipeline_status Ruft den Status der neuesten Pipeline für einen bestimmten Branch ab. Dieses Tool kann auf drei Arten verwendet werden:
  1. Verwenden von Projekt-Slug und Branch (empfohlen):

    • Beispiel: „Status der neuesten Pipeline für mein Projekt auf dem Haupt-Branch abrufen“
  2. Verwenden der CircleCI-Projekt-URL:

  3. Verwenden des lokalen Projektkontexts:

    • Funktioniert aus Ihrem lokalen Arbeitsbereich, indem Sie Arbeitsbereichs-Root, Git-Remote-URL und Branchnamen angeben

Beispielausgabe:

---
Workflow: build
Status: success
Duration: 5 minutes
Created: 4/20/2025, 10:15:30 AM
Stopped: 4/20/2025, 10:20:45 AM
---
Workflow: test
Status: running
Duration: unknown
Created: 4/20/2025, 10:21:00 AM
Stopped: in progress
list_artifacts

Ruft die Liste der Artefakte ab, die von einem CircleCI-Job erzeugt wurden. Dieses Tool kann auf drei Arten verwendet werden:

  1. Verwenden von Projekt-Slug und Branch (empfohlen):

    • Verwenden Sie zuerst list_followed_projects, um Ihre Projekte zu erhalten, dann:
    • Beispiel: „Artefakte für mein Projekt auf dem Haupt-Branch auflisten“
  2. Verwenden der CircleCI-URL:

    • Job-URL: https://app.circleci.com/pipelines/gh/organization/project/123/workflows/abc-def/jobs/789
    • Workflow-URL: https://app.circleci.com/pipelines/gh/organization/project/123/workflows/abc-def
    • Pipeline-URL: https://app.circleci.com/pipelines/gh/organization/project/123
  3. Verwenden des lokalen Projektkontexts:

    • Funktioniert aus Ihrem lokalen Arbeitsbereich, indem Sie Arbeitsbereichs-Root, Git-Remote-URL und Branchnamen angeben

Nützlich für:

  • Das Auffinden von Download-URLs für Build-Artefakte (Binärdateien, Berichte, Logs)
  • Das Überprüfen, welche Artefakte von einem Pipeline-Lauf erzeugt wurden
list_component_versions

Listet alle Versionen für eine bestimmte CircleCI-Komponente in einer Umgebung auf. Enthält Bereitstellungsstatus, Commit-Informationen und Zeitstempel.

Das Tool fordert Sie auf, Komponente und Umgebung auszuwählen, falls diese nicht angegeben sind.

Nützlich für:

  • Das Identifizieren, welche Version derzeit live ist
  • Das Auswählen von Zielversionen für Rollback-Operationen
  • Das Abrufen von Bereitstellungsdetails (Pipeline, Workflow, Job)
list_followed_projects

Listet alle Projekte auf, die der Benutzer auf CircleCI verfolgt.

  • Zeigt alle Projekte, auf die Sie Zugriff haben, mit ihrer projectSlug
  • Beispiel: „Meine CircleCI-Projekte auflisten“

Beispielausgabe:

Projects followed:
1. my-project (projectSlug: gh/organization/my-project)
2. another-project (projectSlug: gh/organization/another-project)

[!NOTE] Der projectSlug (nicht der Projektname) wird für viele andere CircleCI-Tools benötigt.

rerun_workflow

Führt einen Workflow von seinem Start oder vom fehlgeschlagenen Job erneut aus.

Gibt die ID des neu erstellten Workflows und einen Link zur Überwachung zurück.

run_pipeline

Löst die Ausführung einer Pipeline aus. Dieses Tool kann auf drei Arten verwendet werden:

  1. Verwenden von Projekt-Slug und Branch (empfohlen):

    • Beispiel: „Pipeline für mein Projekt auf dem Haupt-Branch ausführen“
  2. Verwenden der CircleCI-URL:

  3. Verwenden des lokalen Projektkontexts:

    • Funktioniert aus Ihrem lokalen Arbeitsbereich, indem Sie Arbeitsbereichs-Root, Git-Remote-URL und Branchnamen angeben

Das Tool gibt einen Link zur Überwachung der Pipeline-Ausführung zurück.

run_rollback_pipeline

Löst einen Rollback für ein CircleCI-Projekt aus. Das Tool führt Sie interaktiv durch:

  1. Projektauswahl — listet verfolgte Projekte zur Auswahl auf
  2. Umgebungsauswahl — listet verfügbare Umgebungen auf (automatische Auswahl, falls nur eine vorhanden ist)
  3. Komponentenauswahl — listet verfügbare Komponenten auf (automatische Auswahl, falls nur eine vorhanden ist)
  4. Versionsauswahl — zeigt verfügbare Versionen an; Sie wählen das Ziel für den Rollback
  5. Rollback-Modus-Erkennung — prüft, ob eine Rollback-Pipeline konfiguriert ist
  6. Rollback ausführen — zwei Optionen:
    • Pipeline-Rollback: löst die Rollback-Pipeline aus
    • Workflow-Wiederholung: führt einen früheren Workflow mithilfe seiner Workflow-ID erneut aus
  7. Bestätigung — fasst zusammen und bestätigt vor der Ausführung

Fehlerbehebung

Schnelle Lösungen

Häufigste Probleme:

  1. Paketcaches leeren:

    npx clear-npx-cache
    npm cache clean --force
    
  2. Neueste Version erzwingen: Fügen Sie @latest zu Ihrer Konfiguration hinzu:

    "args": ["-y", "@circleci/mcp-server-circleci@latest"]
    
  3. Starten Sie Ihre IDE vollständig neu (nicht nur das Fenster neu laden)

Authentifizierungsprobleme
  • Ungültige Token-Fehler: Überprüfen Sie Ihre CIRCLECI_TOKEN unter Persönliche API-Tokens
  • Berechtigungsfehler: Stellen Sie sicher, dass das Token Lesezugriff auf Ihre Projekte hat
  • Umgebungsvariablen werden nicht geladen: Testen Sie mit echo $CIRCLECI_TOKEN (Mac/Linux) oder echo %CIRCLECI_TOKEN% (Windows)
Verbindungs- und Netzwerkprobleme
  • Basis-URL: Bestätigen Sie, dass CIRCLECI_BASE_URL https://circleci.com ist
  • Unternehmensnetzwerke: Konfigurieren Sie npm-Proxy-Einstellungen, falls Sie sich hinter einer Firewall befinden
  • Firewall-Blockierung: Prüfen Sie, ob Sicherheitssoftware Paketdownloads blockiert
Systemanforderungen
  • Node.js-Version: Stellen Sie sicher, dass >= 18.0.0 mit node --version vorliegt
  • Node.js aktualisieren: Ziehen Sie das neueste LTS in Betracht, wenn Kompatibilitätsprobleme auftreten
  • Paketmanager: Überprüfen Sie, ob npm/pnpm funktioniert: npm --version
IDE-spezifische Probleme
  • Konfigurationsdatei-Speicherort: Überprüfen Sie den Pfad für Ihr Betriebssystem noch einmal
  • Syntaxfehler: Validieren Sie die JSON-Syntax in Ihrer Konfigurationsdatei
  • Konsolenprotokolle: Überprüfen Sie die Entwicklerkonsole der IDE auf spezifische Fehler
  • Andere IDE testen: Testen Sie in einem anderen unterstützten Editor, um das Problem einzugrenzen
Prozessprobleme

Hängende Prozesse — vorhandene MCP-Prozesse beenden:

# Mac/Linux:
pkill -f "mcp-server-circleci"

# Windows:
taskkill /f /im node.exe

Portkonflikte: Starten Sie Ihre IDE neu, wenn die Verbindung blockiert scheint.

Erweiterte Fehlersuche
  • Paket direkt testen: npx @circleci/mcp-server-circleci@latest --help
  • Ausführliche Protokollierung: DEBUG=* npx @circleci/mcp-server-circleci@latest
  • Docker-Fallback: Versuchen Sie die Docker-Installation, wenn npx wiederholt fehlschlägt

Benötigen Sie weitere Hilfe?

  1. Überprüfen Sie GitHub Issues auf ähnliche Probleme
  2. Geben Sie bei der Fehlermeldung Ihr Betriebssystem, die Node-Version und die IDE an
  3. Teilen Sie relevante Fehlermeldungen aus der IDE-Konsole mit

Telemetrie

Der Server unterstützt OpenTelemetry-Metriken zur Verfolgung der Tool-Nutzung. Metriken werden exportiert, sofern Sie nicht DISABLE_TELEMETRY=true festlegen. Bei Remote-Bereitstellungen verwenden die Metriken denselben Token wie die Anfrage (pro Benutzer-PAT oder gemeinsamer Server-PAT).

MetrikBeschreibung
circleci.mcp.tool.invocationsAnzahl der Tool-Aufrufe
circleci.mcp.tool.duration_msAusführungszeit in ms
circleci.mcp.tool.errorsAnzahl der Fehler

Entwicklung

Erste Schritte

  1. Klonen Sie das Repository:

    git clone https://github.com/CircleCI-Public/mcp-server-circleci.git
    cd mcp-server-circleci
    
  2. Installieren Sie die Abhängigkeiten:

    pnpm install
    
  3. Erstellen Sie das Projekt:

    pnpm build
    

Docker-Container bauen

Sie können den Docker-Container lokal mit folgendem Befehl erstellen:

docker build -t circleci:mcp-server-circleci .

Dadurch wird ein Docker-Image mit dem Tag circleci:mcp-server-circleci erstellt, das Sie mit jedem MCP-Client verwenden können.

Lokaler Stdio-Modus (einzelner Entwickler, Token auf dem Client):

docker run --rm -i \
  -e CIRCLECI_TOKEN=your-circleci-token \
  -e CIRCLECI_BASE_URL=https://circleci.com \
  circleci/mcp-server-circleci

Remote-Modus (zentraler Server für ein Team): siehe Self-Managed Remote MCP Server.

Entwicklung mit MCP Inspector

Der einfachste Weg, den MCP-Server zu iterieren, ist die Verwendung des MCP-Inspectors. Weitere Informationen zum MCP-Inspector finden Sie unter https://modelcontextprotocol.io/docs/tools/inspector

  1. Starten Sie den Entwicklungsserver:

    pnpm watch # Keep this running in one terminal
    
  2. Starten Sie in einem separaten Terminal den Inspector:

    pnpm inspector
    
  3. Konfigurieren Sie die Umgebung:

    • Fügen Sie Ihre CIRCLECI_TOKEN im Abschnitt „Umgebungsvariablen“ der Inspector-Oberfläche hinzu
    • Das Token benötigt Lesezugriff auf Ihre CircleCI-Projekte
    • Optional können Sie Ihre CircleCI-Basis-URL festlegen (Standard: https://circleci.com)

Tests

  • Führen Sie die Testsuite aus:

    pnpm test
    
  • Führen Sie Tests im Watch-Modus während der Entwicklung aus:

    pnpm test:watch
    

Detailliertere Richtlinien für Beiträge finden Sie unter CONTRIBUTING.md