CircleCI
offiziellErmöglicht KI-Agenten, Build-Fehler von CircleCI zu beheben.
Was kann man mit CircleCI MCP machen?
- CircleCI-Konfiguration validieren — Lassen Sie Ihre
.circleci/config.ymlauf Syntax- und Semantikfehler überconfig_helperprü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_pipelineoder führen Sie einen Workflow von Anfang oder ab einem fehlgeschlagenen Job überrerun_workflowerneut aus. - Build-Fehler untersuchen — Rufen Sie detaillierte Fehlerprotokolle mit
get_build_failure_logsund Testergebnisse überget_job_test_resultsab. - 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_dataherunter und finden Sie untergenutzte Ressourcenklassen überfind_underused_resource_classes.
Dokumentation
[!IMPORTANT] Dieses Paket ist veraltet. Bitte migrieren.
@circleci/mcp-server-circlecierhä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
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
| Tool | Beschreibung |
|---|---|
config_helper | Validieren und erhalten Sie Anleitungen für Ihre CircleCI-Konfiguration |
download_usage_api_data | Laden Sie Nutzungsdaten von der CircleCI Usage API herunter |
find_flaky_tests | Identifizieren Sie flaky Tests durch Analyse der Testausführungshistorie |
find_underused_resource_classes | Finden Sie Jobs mit ungenutzten Rechenressourcen |
get_build_failure_logs | Rufen Sie detaillierte Fehlerprotokolle von CircleCI-Builds ab |
get_job_test_results | Rufen Sie Testmetadaten und -ergebnisse für CircleCI-Jobs ab |
get_latest_pipeline_status | Erhalten Sie den Status der neuesten Pipeline für einen Branch |
list_artifacts | Listen Sie Artefakte auf, die von einem CircleCI-Job erzeugt wurden |
list_component_versions | Listen Sie alle Versionen für eine CircleCI-Komponente auf |
list_followed_projects | Listen Sie alle CircleCI-Projekte auf, denen Sie folgen |
rerun_workflow | Führen Sie einen Workflow von Anfang oder vom fehlgeschlagenen Job erneut aus |
run_pipeline | Lösen Sie eine Pipeline aus |
run_rollback_pipeline | Lö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:
- CircleCI-Personal-API-Token (mehr erfahren)
- NPX: Node.js >= v18 und pnpm
- Docker: Docker
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_URList optional – nur für On-Premises-Kunden erforderlich.MAX_MCP_OUTPUT_LENGTHist 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:
- CircleCI-Personal-API-Token (mehr erfahren)
- NPX: Node.js >= v18 und pnpm
- Docker: Docker
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:
- CircleCI-Personal-API-Token (mehr erfahren)
- NPX: Node.js >= v18 und pnpm
- Docker: Docker
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:
- CircleCI-Personal-API-Token (mehr erfahren)
- NPX: Node.js >= v18 und pnpm
- Docker: Docker
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:
- CircleCI-Personal-API-Token (mehr erfahren)
- NPX: Node.js >= v18 und pnpm
- Docker: Docker
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:
- Rufen Sie die MCP-Konfigurationsoberfläche auf
- Wählen Sie das Symbol +
- Wählen Sie den Bereich: global oder lokal
- Geben Sie einen Namen ein (z. B.
circleci-remote-mcp) - Wählen Sie das Transportprotokoll: stdio
- Geben Sie den Befehlspfad zu Ihrem Skript ein
- 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
| Modus | Wann verwenden | Server-Einrichtung | Client-Einrichtung | CircleCI-Überwachungspfad |
|---|---|---|---|---|
| Pro-Benutzer-Tokens (empfohlen) | Teams mit SSO-gestützten Personal-API-Tokens | REQUIRE_REQUEST_TOKEN=true, kein Server-PAT | Jeder Entwickler leitet sein PAT weiter | Pro Entwickler |
| Gemeinsames Token (interim) | Schnelle Einführung, einzelne Dienstidentität OK | CIRCLECI_TOKEN auf dem Server, REQUIRE_REQUEST_TOKEN=false (expliziter Opt-out) | Kein Auth-Header erforderlich | Einzelne 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 dieCIRCLECI_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=falsemit einer Nicht-Loopback-Bind-Adresse kombiniert wird, es sei denn, Sie akzeptieren das Risiko explizit mitMCP_ALLOW_UNAUTHENTICATED_NETWORK_ACCESS=true. DieHost/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:
| Variable | Beschreibung |
|---|---|
start=remote | Startet den HTTP+SSE-MCP-Server anstelle von stdio |
port | Lauschender Port im Container (Standard: 8000) |
REQUIRE_REQUEST_TOKEN | Anfragen 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_TOKEN | Gemeinsames Fallback-PAT für alle Anfragen, wenn keine benutzerspezifischen Header gesendet werden |
CIRCLECI_BASE_URL | Optional – nur für On-Premises erforderlich (Standard: https://circleci.com) |
DISABLE_TELEMETRY=true | Deaktiviert den Export von Nutzungsmetriken |
MCP_ALLOWED_HOSTS | Kommagetrennte 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_ORIGINS | Kommagetrennte 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_HOST | Netzwerk-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_ACCESS | Erforderlich (=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_ROOTS | Kommagetrennte 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) undfind_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_modulesund 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 –
/workspacein einem Container,/srv,/opt, ein sekundäres Volume wie/Volumes/work– setzen SieMCP_FILE_OUTPUT_ROOTSauf 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üssenMCP_ALLOWED_HOSTSauf den Hostnamen setzen, den Clients verwenden, andernfalls erhalten alle/mcp-Anforderungen403 Forbidden. Der/ping-Health-Check-Endpunkt ist nicht geschützt, sodass Load-Balancer-Probes unabhängig vonHostweiterhin funktionieren.Der
Origin-Header (von Browsern gesendet) wird ebenfalls validiert, wenn er vorhanden ist. Nicht-Browser-Clients wiemcp-remotesenden nieOrigin, 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
Hostsenden undOriginweglassen 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 vonREQUIRE_REQUEST_TOKEN(oder eines authentifizierenden Proxys vor dem Port). Die Anforderung einesOrigin-Headers würde jeden legitimen CLI-Client brechen, während kein Angreifer gestoppt wird.Hinter einem Reverse-Proxy: Wenn Ihr Proxy
Hostauf die Backend-Adresse umschreibt (Standard bei nginx), fügen Sieproxy_set_header Host $host;hinzu, um den ursprünglichen Hostnamen durchzureichen, und setzen Sie dannMCP_ALLOWED_HOSTSauf diesen öffentlichen Hostnamen. Alternativ setzen SieMCP_ALLOWED_HOSTSauf 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/mcpmit--allow-httpfür lokale Tests. In Produktion beenden Sie TLS an Ihrem Ingress/Load-Balancer und verwenden Siehttps://your-host/mcpohne--allow-http.
Windows: Vermeiden Sie Leerzeichen um den Doppelpunkt in
--header-Werten. Platzieren Sie den vollständigenBearer <token>-Wert in einer Umgebungsvariablen.
Sicherheit: Die Beispiele verwenden
npxder Einfachheit halber. Verwenden Sie für Produktions- oder Team-Rollouts eine bestimmte Version in Ihrer MCP-Konfiguration (z. B.mcp-remote@0.1.38stattmcp-remote). Verwenden Sie keine Versionen unter0.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.ymlauf 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:
-
Mit Projekt-Slug (empfohlen):
- Verwenden Sie zuerst
list_followed_projects, um Ihre Projekte zu erhalten, dann: - Beispiel: „Flaky-Tests für mein Projekt abrufen“
- Verwenden Sie zuerst
-
Mit CircleCI-Projekt-URL:
- Beispiel: „Flaky-Tests in https://app.circleci.com/pipelines/github/org/repo finden“
-
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_DIRECTORYenv 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:
-
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“
- Verwenden Sie zuerst
-
Mit CircleCI-URLs:
- Geben Sie direkt eine fehlgeschlagene Job-URL oder Pipeline-URL an
- Beispiel: „Logs von https://app.circleci.com/pipelines/github/org/repo/123 abrufen“
-
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:
-
Mit Projekt-Slug und Branch (empfohlen):
- Beispiel: „Testergebnisse für mein Projekt im Haupt-Branch abrufen“
-
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
- Job-URL:
-
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:
-
Verwenden von Projekt-Slug und Branch (empfohlen):
- Beispiel: „Status der neuesten Pipeline für mein Projekt auf dem Haupt-Branch abrufen“
-
Verwenden der CircleCI-Projekt-URL:
- Beispiel: „Status der neuesten Pipeline für https://app.circleci.com/pipelines/github/org/repo abrufen“
-
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:
-
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“
- Verwenden Sie zuerst
-
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
- Job-URL:
-
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:
-
Verwenden von Projekt-Slug und Branch (empfohlen):
- Beispiel: „Pipeline für mein Projekt auf dem Haupt-Branch ausführen“
-
Verwenden der CircleCI-URL:
- Pipeline-URL, Workflow-URL, Job-URL oder Projekt-URL mit Branch
- Beispiel: „Pipeline für https://app.circleci.com/pipelines/github/org/repo/123 ausführen“
-
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:
- Projektauswahl — listet verfolgte Projekte zur Auswahl auf
- Umgebungsauswahl — listet verfügbare Umgebungen auf (automatische Auswahl, falls nur eine vorhanden ist)
- Komponentenauswahl — listet verfügbare Komponenten auf (automatische Auswahl, falls nur eine vorhanden ist)
- Versionsauswahl — zeigt verfügbare Versionen an; Sie wählen das Ziel für den Rollback
- Rollback-Modus-Erkennung — prüft, ob eine Rollback-Pipeline konfiguriert ist
- 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
- Bestätigung — fasst zusammen und bestätigt vor der Ausführung
Fehlerbehebung
Schnelle Lösungen
Häufigste Probleme:
-
Paketcaches leeren:
npx clear-npx-cache npm cache clean --force -
Neueste Version erzwingen: Fügen Sie
@latestzu Ihrer Konfiguration hinzu:"args": ["-y", "@circleci/mcp-server-circleci@latest"] -
Starten Sie Ihre IDE vollständig neu (nicht nur das Fenster neu laden)
Authentifizierungsprobleme
- Ungültige Token-Fehler: Überprüfen Sie Ihre
CIRCLECI_TOKENunter 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) oderecho %CIRCLECI_TOKEN%(Windows)
Verbindungs- und Netzwerkprobleme
- Basis-URL: Bestätigen Sie, dass
CIRCLECI_BASE_URLhttps://circleci.comist - 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 --versionvorliegt - 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?
- Überprüfen Sie GitHub Issues auf ähnliche Probleme
- Geben Sie bei der Fehlermeldung Ihr Betriebssystem, die Node-Version und die IDE an
- 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).
| Metrik | Beschreibung |
|---|---|
circleci.mcp.tool.invocations | Anzahl der Tool-Aufrufe |
circleci.mcp.tool.duration_ms | Ausführungszeit in ms |
circleci.mcp.tool.errors | Anzahl der Fehler |
Entwicklung
Erste Schritte
-
Klonen Sie das Repository:
git clone https://github.com/CircleCI-Public/mcp-server-circleci.git cd mcp-server-circleci -
Installieren Sie die Abhängigkeiten:
pnpm install -
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
-
Starten Sie den Entwicklungsserver:
pnpm watch # Keep this running in one terminal -
Starten Sie in einem separaten Terminal den Inspector:
pnpm inspector -
Konfigurieren Sie die Umgebung:
- Fügen Sie Ihre
CIRCLECI_TOKENim 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)
- Fügen Sie Ihre
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