CircleCI MCP-Server
Model Context Protocol (MCP) ist ein neues, standardisiertes Protokoll zur Verwaltung des Kontexts zwischen großen Sprachmodellen (LLMs) und externen Systemen. In diesem Repository stellen wir einen MCP-Server für CircleCI bereit.
Auf diese Weise können Sie Cursor IDE, Windsurf, Copilot oder jeden MCP-unterstützten Client verwenden, um mithilfe natürlicher Sprache Dinge mit CircleCI zu erreichen, z. B.:
https://github.com/user-attachments/assets/3c765985-8827-442a-a8dc-5069e01edb74
Anforderungen
Für die NPX-Installation:
Für die Docker-Installation:
Installation
Cursor
Verwenden von NPX
Fügen Sie Ihrer Cursor-MCP-Konfiguration Folgendes hinzu:
{
"mcpServers": {
"circleci-mcp-server": {
"command": "npx",
"args": ["-y", "@circleci/mcp-server-circleci"],
"env": {
"CIRCLECI_TOKEN": "your-circleci-token",
"CIRCLECI_BASE_URL": "https://circleci.com" // Optional - required for on-prem customers only
}
}
}
}
Verwenden von Docker
Fügen Sie Ihrer Cursor-MCP-Konfiguration Folgendes hinzu:
{
"mcpServers": {
"circleci-mcp-server": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-e", "CIRCLECI_TOKEN",
"-e", "CIRCLECI_BASE_URL",
"circleci:mcp-server-circleci"
],
"env": {
"CIRCLECI_TOKEN": "your-circleci-token",
"CIRCLECI_BASE_URL": "https://circleci.com" // Optional - required for on-prem customers only
}
}
}
}
VS Code
Verwenden von NPX
So installieren Sie den CircleCI MCP-Server für VS Code in .vscode/mcp.json :
{
// 💡 Inputs are prompted on first server start, then stored securely by VS Code.
"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": {
// https://github.com/ppl-ai/modelcontextprotocol/
"circleci-mcp-server": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@circleci/mcp-server-circleci"],
"env": {
"CIRCLECI_TOKEN": "${input:circleci-token}",
"CIRCLECI_BASE_URL": "${input:circleci-base-url}"
}
}
}
}
Verwenden von Docker
So installieren Sie den CircleCI MCP-Server für VS Code in .vscode/mcp.json mit Docker:
{
// 💡 Inputs are prompted on first server start, then stored securely by VS Code.
"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": {
// https://github.com/ppl-ai/modelcontextprotocol/
"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}"
}
}
}
}
Claude Desktop
Verwenden von NPX
Fügen Sie Ihrer claude_desktop_config.json Folgendes hinzu:
{
"mcpServers": {
"circleci-mcp-server": {
"command": "npx",
"args": ["-y", "@circleci/mcp-server-circleci"],
"env": {
"CIRCLECI_TOKEN": "your-circleci-token",
"CIRCLECI_BASE_URL": "https://circleci.com" // Optional - required for on-prem customers only
}
}
}
}
Verwenden von Docker
Fügen Sie Ihrer claude_desktop_config.json Folgendes hinzu:
{
"mcpServers": {
"circleci-mcp-server": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-e", "CIRCLECI_TOKEN",
"-e", "CIRCLECI_BASE_URL",
"circleci:mcp-server-circleci"
],
"env": {
"CIRCLECI_TOKEN": "your-circleci-token",
"CIRCLECI_BASE_URL": "https://circleci.com" // Optional - required for on-prem customers only
}
}
}
}
Um diese Datei zu finden/erstellen, öffnen Sie zunächst die Claude-Desktop-Einstellungen. Klicken Sie dann links im Einstellungsbereich auf „Entwickler“ und anschließend auf „Konfiguration bearbeiten“.
Dadurch wird eine Konfigurationsdatei erstellt unter:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
Weitere Informationen zur Verwendung von MCP-Servern mit Claude Desktop finden Sie in der folgenden Anleitung: https://modelcontextprotocol.io/quickstart/user
Claude Code
Verwenden von NPX
Führen Sie nach der Installation von Claude Code den folgenden Befehl aus:
claude mcp add circleci-mcp-server -e CIRCLECI_TOKEN=your-circleci-token -- npx -y @circleci/mcp-server-circleci
Verwenden von Docker
Führen Sie nach der Installation von Claude Code den folgenden Befehl aus:
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
Weitere Informationen zur Verwendung von MCP-Servern mit Claude Code finden Sie in der folgenden Anleitung: https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/tutorials#set-up-model-context-protocol-mcp
Windsurf
Verwenden von NPX
Fügen Sie Ihrer Windsurf-mcp_config.json Folgendes hinzu:
{
"mcpServers": {
"circleci-mcp-server": {
"command": "npx",
"args": ["-y", "@circleci/mcp-server-circleci"],
"env": {
"CIRCLECI_TOKEN": "your-circleci-token",
"CIRCLECI_BASE_URL": "https://circleci.com" // Optional - required for on-prem customers only
}
}
}
}
Verwenden von Docker
Fügen Sie Ihrer Windsurf-mcp_config.json Folgendes hinzu:
{
"mcpServers": {
"circleci-mcp-server": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-e", "CIRCLECI_TOKEN",
"-e", "CIRCLECI_BASE_URL",
"circleci:mcp-server-circleci"
],
"env": {
"CIRCLECI_TOKEN": "your-circleci-token",
"CIRCLECI_BASE_URL": "https://circleci.com" // Optional - required for on-prem customers only
}
}
}
}
Weitere Informationen zur Verwendung von MCP-Servern mit Windsurf finden Sie in der folgenden Anleitung: https://docs.windsurf.com/windsurf/mcp
Installation über Smithery
So installieren Sie CircleCI MCP Server für Claude Desktop automatisch über Smithery :
npx -y @smithery/cli install @CircleCI-Public/mcp-server-circleci --client claude
Merkmale
get_build_failure_logsRuft detaillierte Fehlerprotokolle von CircleCI-Builds ab. Dieses Tool kann auf drei Arten verwendet werden:- Verwenden von Projekt-Slug und Branch (empfohlener Arbeitsablauf):
- Listen Sie zunächst Ihre verfügbaren Projekte auf:
- Verwenden Sie das Tool list_followed_projects, um Ihre Projekte zu erhalten
- Beispiel: „Liste meine CircleCI-Projekte auf“
- Wählen Sie dann das Projekt aus, dem ein ProjektSlug zugeordnet ist
- Beispiel: „Lasst uns mein Projekt verwenden“
- Fordern Sie dann an, die Build-Fehlerprotokolle für einen bestimmten Zweig abzurufen:
- Beispiel: „Build-Fehler für mein Projekt im Hauptzweig abrufen“
- Verwenden von CircleCI-URLs:
- Lokalen Projektkontext verwenden:
- Funktioniert von Ihrem lokalen Arbeitsbereich aus, indem Folgendes bereitgestellt wird:
- Stammpfad des Arbeitsbereichs
- Git-Remote-URL
- Filialname
- Beispiel: „Suchen Sie die letzte fehlgeschlagene Pipeline in meinem aktuellen Zweig.“
Das Tool gibt formatierte Protokolle zurück, darunter:
- Jobnamen
- Schrittweise Ausführungsdetails
- Fehlermeldungen und Kontext
Dies ist besonders nützlich für:
- Debuggen fehlgeschlagener Builds
- Analysieren von Testfehlern
- Untersuchen von Bereitstellungsproblemen
- Schneller Zugriff auf Build-Protokolle, ohne Ihre IDE zu verlassen
find_flaky_testsIdentifiziert fehlerhafte Tests in Ihrem CircleCI-Projekt durch Analyse des Testausführungsverlaufs. Dies nutzt die hier beschriebene Funktion zur Erkennung fehlerhafter Tests: https://circleci.com/blog/introducing-test-insights-with-flaky-test-detection/#flaky-test-detectionDieses Tool kann auf drei Arten verwendet werden:- Verwenden von Project Slug (empfohlener Arbeitsablauf):
- Listen Sie zunächst Ihre verfügbaren Projekte auf:
- Verwenden Sie das Tool list_followed_projects, um Ihre Projekte zu erhalten
- Beispiel: „Liste meine CircleCI-Projekte auf“
- Wählen Sie dann das Projekt aus, dem ein ProjektSlug zugeordnet ist
- Beispiel: „Lasst uns mein Projekt verwenden“
- Fordern Sie dann an, die fehlerhaften Tests abzurufen:
- Beispiel: „Holen Sie sich fehlerhafte Tests für mein Projekt“
- Verwenden der CircleCI-Projekt-URL:
- Lokalen Projektkontext verwenden:
- Funktioniert von Ihrem lokalen Arbeitsbereich aus, indem Folgendes bereitgestellt wird:
- Stammpfad des Arbeitsbereichs
- Git-Remote-URL
- Beispiel: „Finden Sie fehlerhafte Tests in meinem aktuellen Projekt.“
Das Tool gibt detaillierte Informationen zu fehlerhaften Tests zurück, darunter:
- Testnamen und Dateispeicherorte
- Fehlermeldungen und Kontexte
Dies hilft Ihnen:
- Identifizieren Sie unzuverlässige Tests in Ihrer Testsuite
- Erhalten Sie detaillierten Kontext zu Testfehlern
- Treffen Sie datenbasierte Entscheidungen zur Testverbesserung
get_latest_pipeline_statusRuft den Status der neuesten Pipeline für einen bestimmten Zweig ab. Dieses Tool kann auf drei Arten verwendet werden:- Verwenden von Projekt-Slug und Branch (empfohlener Arbeitsablauf):
- Listen Sie zunächst Ihre verfügbaren Projekte auf:
- Verwenden Sie das Tool list_followed_projects, um Ihre Projekte zu erhalten
- Beispiel: „Liste meine CircleCI-Projekte auf“
- Wählen Sie dann das Projekt aus, dem ein ProjektSlug zugeordnet ist
- Beispiel: „Lasst uns mein Projekt verwenden“
- Fordern Sie dann an, den neuesten Pipeline-Status für einen bestimmten Zweig abzurufen:
- Beispiel: „Status der neuesten Pipeline für mein Projekt im Hauptzweig abrufen“
- Verwenden der CircleCI-Projekt-URL:
- Lokalen Projektkontext verwenden:
- Funktioniert von Ihrem lokalen Arbeitsbereich aus, indem Folgendes bereitgestellt wird:
- Stammpfad des Arbeitsbereichs
- Git-Remote-URL
- Filialname
- Beispiel: „Status der neuesten Pipeline für mein aktuelles Projekt abrufen“
Das Tool gibt einen formatierten Status der neuesten Pipeline zurück:
- Workflow-Namen und ihr aktueller Status
- Dauer jedes Workflows
- Zeitstempel für Erstellung und Abschluss
- Gesamtzustand der Pipeline
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
Dies ist besonders nützlich für:
- Überprüfen des Status der neuesten Pipeline
- Abrufen des Status der neuesten Pipeline für einen bestimmten Zweig
- Schnelles Überprüfen des Status der neuesten Pipeline, ohne Ihre IDE zu verlassen
get_job_test_resultsRuft Testmetadaten für CircleCI-Jobs ab und ermöglicht Ihnen die Analyse von Testergebnissen, ohne Ihre IDE zu verlassen. Dieses Tool kann auf drei Arten verwendet werden:- Verwenden von Projekt-Slug und Branch (empfohlener Arbeitsablauf):
- Listen Sie zunächst Ihre verfügbaren Projekte auf:
- Verwenden Sie das Tool list_followed_projects, um Ihre Projekte zu erhalten
- Beispiel: „Liste meine CircleCI-Projekte auf“
- Wählen Sie dann das Projekt aus, dem ein ProjektSlug zugeordnet ist
- Beispiel: „Lasst uns mein Projekt verwenden“
- Fordern Sie dann an, die Testergebnisse für einen bestimmten Zweig abzurufen:
- Beispiel: „Testergebnisse für mein Projekt im Hauptzweig abrufen“
- Verwenden der CircleCI-URL:
- Lokalen Projektkontext verwenden:
- Funktioniert von Ihrem lokalen Arbeitsbereich aus, indem Folgendes bereitgestellt wird:
- Stammpfad des Arbeitsbereichs
- Git-Remote-URL
- Filialname
- Beispiel: „Testergebnisse für mein aktuelles Projekt im Hauptzweig abrufen“
Das Tool gibt detaillierte Informationen zu den Testergebnissen zurück:
- Zusammenfassung aller Tests (Gesamt, Erfolgreich, Nicht bestanden)
- Detaillierte Informationen zu fehlgeschlagenen Tests, einschließlich:
- Testname und Klasse
- Dateispeicherort
- Fehlermeldungen
- Laufzeit
- Liste erfolgreicher Tests mit Zeitinformationen
- Nach Testergebnissen filtern
Dies ist besonders nützlich für:
- Schnelle Analyse von Testfehlern ohne Besuch der CircleCI-Web-Benutzeroberfläche
- Erkennen von Mustern bei Testfehlern
- Finden langsamer Tests, die möglicherweise optimiert werden müssen
- Überprüfen der Testabdeckung in Ihrem gesamten Projekt
- Fehlerbehebung bei fehlerhaften Tests
Hinweis: Das Tool erfordert, dass die Testmetadaten in Ihrer CircleCI-Konfiguration korrekt konfiguriert sind. Weitere Informationen zum Einrichten der Testmetadatenerfassung finden Sie unter: https://circleci.com/docs/collect-test-data/
config_helperUnterstützt CircleCI-Konfigurationsaufgaben durch Anleitung und Validierung. Dieses Tool hilft Ihnen:- CircleCI-Konfiguration validieren:
- Überprüft Ihre .circleci/config.yml auf Syntax- und Semantikfehler
- Beispiel: „Meine CircleCI-Konfiguration validieren“
Das Tool bietet:
- Detaillierte Validierungsergebnisse
- Konfigurationsempfehlungen
Dies hilft Ihnen:
- Fangen Sie Konfigurationsfehler ab, bevor Sie pushen
- Erfahren Sie mehr über die Best Practices für die CircleCI-Konfiguration
- Beheben von Konfigurationsproblemen
- CircleCI-Funktionen richtig implementieren
create_prompt_templateHilft bei der Erstellung strukturierter Eingabevorlagen für KI-gestützte Anwendungen basierend auf Funktionsanforderungen. Dieses Tool:- Wandelt Funktionsanforderungen in strukturierte Eingabeaufforderungen um:
- Wandelt Benutzeranforderungen in optimierte Eingabevorlagen um
- Beispiel: „Erstellen Sie eine Vorlage für die Erstellung von Gutenachtgeschichten nach Alter und Thema.“
Das Tool bietet:
- Eine strukturierte Eingabeaufforderungsvorlage
- Ein Kontextschema, das die erforderlichen Eingabeparameter definiert
Dies hilft Ihnen:
- Erstellen Sie effektive Eingabeaufforderungen für KI-Anwendungen
- Standardisieren Sie Eingabeparameter für konsistente Ergebnisse
- Erstellen Sie robuste KI-gestützte Funktionen
recommend_prompt_template_testsGeneriert Testfälle für Eingabevorlagen, um sicherzustellen, dass sie die erwarteten Ergebnisse liefern. Dieses Tool:- Bietet Testfälle für Eingabeaufforderungsvorlagen:
- Erstellt verschiedene Testszenarien basierend auf Ihrer Eingabeaufforderungsvorlage und Ihrem Kontextschema
- Beispiel: „Tests für meine Vorlage für Gutenachtgeschichten erstellen“
Das Tool bietet:
- Eine Reihe empfohlener Testfälle
- Verschiedene Parameterkombinationen zum Testen der Vorlagenrobustheit
Dies hilft Ihnen:
- Überprüfen der Funktionalität der Eingabeaufforderungsvorlage
- Gewährleisten Sie konsistente KI-Reaktionen über alle Eingaben hinweg
- Identifizieren Sie Randfälle und potenzielle Probleme
- Verbessern Sie die Gesamtqualität Ihrer KI-Anwendungen
list_followed_projectsListet alle Projekte auf, denen der Benutzer auf CircleCI folgt. Dieses Tool:- Ruft Projekte ab und zeigt sie an:
- Zeigt alle Projekte an, auf die der Benutzer Zugriff hat und die er verfolgt
- Gibt den Projektnamen und den Projekt-Slug für jeden Eintrag an
- Beispiel: „Liste meine CircleCI-Projekte auf“
Das Tool gibt eine formatierte Liste von Projekten zurück, Beispielausgabe:
Projects followed:
1. my-project (projectSlug: gh/organization/my-project)
2. another-project (projectSlug: gh/organization/another-project)
Dies ist besonders nützlich für:
- Identifizieren, welche CircleCI-Projekte für Sie verfügbar sind
- Abrufen des für andere CircleCI-Tools benötigten Projekt-Slugs
- Auswählen eines Projekts für nachfolgende Vorgänge
Hinweis: Der ProjectSlug (nicht der Projektname) wird für viele andere CircleCI-Tools benötigt und wird für diese Tool-Aufrufe verwendet, nachdem ein Projekt ausgewählt wurde.
run_pipelineLöst die Ausführung einer Pipeline aus. Dieses Tool kann auf drei Arten verwendet werden:- Verwenden von Projekt-Slug und Branch (empfohlener Arbeitsablauf):
- Listen Sie zunächst Ihre verfügbaren Projekte auf:
- Verwenden Sie das Tool list_followed_projects, um Ihre Projekte zu erhalten
- Beispiel: „Liste meine CircleCI-Projekte auf“
- Wählen Sie dann das Projekt aus, dem ein ProjektSlug zugeordnet ist
- Beispiel: „Lasst uns mein Projekt verwenden“
- Fordern Sie dann an, die Pipeline für einen bestimmten Zweig auszuführen:
- Beispiel: „Führen Sie die Pipeline für mein Projekt im Hauptzweig aus.“
- Verwenden der CircleCI-URL:
- Lokalen Projektkontext verwenden:
- Funktioniert von Ihrem lokalen Arbeitsbereich aus, indem Folgendes bereitgestellt wird:
- Stammpfad des Arbeitsbereichs
- Git-Remote-URL
- Filialname
- Beispiel: „Führen Sie die Pipeline für mein aktuelles Projekt im Hauptzweig aus.“
Das Tool gibt einen Link zur Überwachung der Pipeline-Ausführung zurück.
Dies ist besonders nützlich für:
- Schnelles Ausführen von Pipelines ohne Besuch der CircleCI-Web-Benutzeroberfläche
- Ausführen von Pipelines aus einem bestimmten Zweig
Entwicklung
Erste Schritte
- Klonen Sie das Repository:
git clone https://github.com/CircleCI-Public/mcp-server-circleci.git
cd mcp-server-circleci
- Installieren Sie Abhängigkeiten:
- Erstellen Sie das Projekt:
Docker-Container erstellen
Sie können den Docker-Container lokal erstellen mit:
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.
So führen Sie den Container aus:
docker run --rm -i -e CIRCLECI_TOKEN=your-circleci-token -e CIRCLECI_BASE_URL=https://circleci.com circleci:mcp-server-circleci
Entwicklung mit MCP Inspector
Die einfachste Möglichkeit, auf dem MCP-Server zu iterieren, ist die Verwendung des MCP-Inspektors. Weitere Informationen zum MCP-Inspektor finden Sie unter https://modelcontextprotocol.io/docs/tools/inspector
- Starten Sie den Entwicklungsserver:
pnpm watch # Keep this running in one terminal
- Starten Sie den Inspector in einem separaten Terminal:
- Konfigurieren Sie die Umgebung:
- Fügen Sie Ihren
CIRCLECI_TOKEN zum Abschnitt „Umgebungsvariablen“ in der Inspektor-Benutzeroberfläche hinzu - Das Token benötigt Lesezugriff auf Ihre CircleCI-Projekte
- Optional können Sie Ihre CircleCI-Basis-URL festlegen. Standardmäßig ist
https//circleci.com
Testen
- Führen Sie die Testsuite aus:
- Führen Sie während der Entwicklung Tests im Überwachungsmodus aus:
Ausführlichere Richtlinien für Beiträge finden Sie unter CONTRIBUTING.md