CircleCI MCP Server
officielPermettre aux agents IA de corriger les échecs de build depuis CircleCI.
Documentation
Serveur MCP CircleCI
Le Model Context Protocol (MCP) est un nouveau protocole standardisé pour gérer le contexte entre les grands modèles de langage (LLM) et les systèmes externes. Dans ce dépôt, nous fournissons un serveur MCP pour CircleCI.
Utilisez Cursor, Windsurf, Copilot, Claude ou tout client compatible MCP pour interagir avec CircleCI en langage naturel — sans quitter votre IDE.
Outils
| Outil | Description |
|---|---|
analyze_diff | Analyser les diffs git par rapport aux règles cursor pour détecter les violations |
config_helper | Valider et obtenir des conseils pour votre configuration CircleCI |
create_prompt_template | Générer des modèles de prompts structurés pour les applications d'IA |
download_usage_api_data | Télécharger les données d'utilisation depuis l'API d'utilisation CircleCI |
find_flaky_tests | Identifier les tests instables en analysant l'historique d'exécution des tests |
find_underused_resource_classes | Trouver les jobs avec des ressources de calcul sous-utilisées |
get_build_failure_logs | Récupérer les journaux d'échec détaillés des builds CircleCI |
get_job_test_results | Récupérer les métadonnées et résultats de test pour les jobs CircleCI |
get_latest_pipeline_status | Obtenir le statut du dernier pipeline pour une branche |
list_artifacts | Lister les artefacts produits par un job CircleCI |
list_component_versions | Lister toutes les versions d'un composant CircleCI |
list_followed_projects | Lister tous les projets CircleCI que vous suivez |
recommend_prompt_template_tests | Générer des cas de test pour les modèles de prompts |
rerun_workflow | Relancer un workflow depuis le début ou depuis le job en échec |
run_evaluation_tests | Exécuter des tests d'évaluation sur un pipeline CircleCI |
run_pipeline | Déclencher l'exécution d'un pipeline |
run_rollback_pipeline | Déclencher un rollback pour un projet |
Installation
Déploiement d'équipe / centralisé : Pour exécuter un serveur distant partagé pour votre organisation (Kubernetes, Docker, etc.) avec des tokens CircleCI par développeur ou partagés, consultez Serveur MCP distant auto-géré.
Cursor
Prérequis :
- Token API personnel CircleCI (en savoir plus)
- NPX : Node.js >= v18 et pnpm
- Docker : Docker
Utilisation de NPX dans un serveur MCP local
Ajoutez ce qui suit à votre configuration Cursor MCP :
{
"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_URLest facultatif — requis uniquement pour les clients on-prem.MAX_MCP_OUTPUT_LENGTHest facultatif — longueur maximale de sortie pour les réponses MCP (par défaut : 50000).
Utilisation de Docker dans un serveur MCP local
Ajoutez ce qui suit à votre configuration Cursor MCP :
{
"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"
}
}
}
}
Utilisation d'un serveur MCP distant auto-géré
Consultez Serveur MCP distant auto-géré. Utilisez la configuration client par utilisateur et ajoutez-la à votre configuration Cursor MCP (Cursor Settings → MCP).
VS Code
Prérequis :
- Token API personnel CircleCI (en savoir plus)
- NPX : Node.js >= v18 et pnpm
- Docker : Docker
Utilisation de NPX dans un serveur MCP local
Ajoutez ce qui suit à .vscode/mcp.json dans votre projet :
{
"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}"
}
}
}
}
💡 Les entrées sont demandées au premier démarrage du serveur, puis stockées de manière sécurisée par VS Code.
Utilisation de Docker dans un serveur MCP local
Ajoutez ce qui suit à .vscode/mcp.json dans votre projet :
{
"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}"
}
}
}
}
Utilisation d'un serveur MCP distant auto-géré
Consultez Serveur MCP distant auto-géré. Utilisez la configuration client par utilisateur dans .vscode/mcp.json.
Claude Desktop
Prérequis :
- Token API personnel CircleCI (en savoir plus)
- NPX : Node.js >= v18 et pnpm
- Docker : Docker
Utilisation de NPX dans un serveur MCP local
Ajoutez ce qui suit à votre claude_desktop_config.json :
{
"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"
}
}
}
}
Utilisation de Docker dans un serveur MCP local
Ajoutez ce qui suit à votre claude_desktop_config.json :
{
"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"
}
}
}
}
Utilisation d'un serveur MCP distant auto-géré
Consultez Serveur MCP distant auto-géré. Créez un script wrapper comme indiqué dans Clients Claude Desktop et CLI, puis pointez votre claude_desktop_config.json vers celui-ci.
Pour trouver ou créer votre fichier de configuration, ouvrez les paramètres de Claude Desktop, cliquez sur Developer dans la barre latérale gauche, puis cliquez sur Edit Config. Le fichier de configuration se trouve à :
- macOS :
~/Library/Application Support/Claude/claude_desktop_config.json - Windows :
%APPDATA%\Claude\claude_desktop_config.json
Pour plus d'informations : https://modelcontextprotocol.io/quickstart/user
Claude Code
Prérequis :
- Token API personnel CircleCI (en savoir plus)
- NPX : Node.js >= v18 et pnpm
- Docker : Docker
Utilisation de NPX dans un serveur MCP local
claude mcp add circleci-mcp-server -e CIRCLECI_TOKEN=your-circleci-token -- npx -y @circleci/mcp-server-circleci@latest
Utilisation de Docker dans un serveur MCP local
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
Utilisation d'un serveur MCP distant auto-géré
Consultez Serveur MCP distant auto-géré et la configuration client Claude Code qui s'y trouve.
Windsurf
Prérequis :
- Token API personnel CircleCI (en savoir plus)
- NPX : Node.js >= v18 et pnpm
- Docker : Docker
Utilisation de NPX dans un serveur MCP local
Ajoutez ce qui suit à votre mcp_config.json Windsurf :
{
"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"
}
}
}
}
Utilisation de Docker dans un serveur MCP local
Ajoutez ce qui suit à votre mcp_config.json Windsurf :
{
"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"
}
}
}
}
Utilisation d'un serveur MCP distant auto-géré
Consultez Serveur MCP distant auto-géré. Utilisez la configuration client par utilisateur dans votre mcp_config.json Windsurf.
Pour plus d'informations : https://docs.windsurf.com/windsurf/mcp
Amazon Q Developer CLI
Prérequis :
La configuration client MCP dans Amazon Q Developer est stockée au format JSON dans un fichier nommé mcp.json. Deux niveaux de configuration sont pris en charge :
- Global :
~/.aws/amazonq/mcp.json— s'applique à tous les espaces de travail - Espace de travail :
.amazonq/mcp.json— spécifique à l'espace de travail courant
Si les deux fichiers existent, leur contenu est fusionné. En cas de conflit, la configuration de l'espace de travail prévaut.
Utilisation de NPX dans un serveur MCP local
Modifiez ~/.aws/amazonq/mcp.json ou créez .amazonq/mcp.json avec ce qui suit :
{
"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
}
}
}
Utilisation d'un serveur MCP distant auto-géré
Consultez Serveur MCP distant auto-géré. Utilisez un script wrapper comme indiqué dans Clients Claude Desktop et CLI, puis enregistrez-le avec q mcp add.
Amazon Q Developer dans l'IDE
Prérequis :
Utilisation de NPX dans un serveur MCP local
Modifiez ~/.aws/amazonq/mcp.json ou créez .amazonq/mcp.json avec ce qui suit :
{
"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
}
}
}
Utilisation d'un serveur MCP distant auto-géré
Consultez Serveur MCP distant auto-géré. Utilisez un script wrapper comme indiqué dans Clients Claude Desktop et CLI, puis ajoutez-le via l'interface de configuration MCP :
- Accédez à l'interface de configuration MCP
- Choisissez le symbole +
- Sélectionnez la portée : global ou local
- Entrez un nom (par ex.
circleci-remote-mcp) - Sélectionnez le protocole de transport : stdio
- Entrez le chemin de la commande vers votre script
- Cliquez sur Save
Smithery
Pour installer le serveur MCP CircleCI pour Claude Desktop automatiquement via Smithery :
npx -y @smithery/cli install @CircleCI-Public/mcp-server-circleci --client claude
Serveur MCP distant auto-géré
Exécutez le serveur MCP de manière centralisée (par exemple sur Kubernetes ou Docker) afin que votre équipe partage un seul déploiement. Choisissez comment les développeurs s'authentifient :
Choisir un mode de déploiement
| Mode | Quand l'utiliser | Configuration serveur | Configuration client | Piste d'audit CircleCI |
|---|---|---|---|---|
| Tokens par utilisateur (recommandé) | Équipes avec des tokens API personnels adossés à SSO | REQUIRE_REQUEST_TOKEN=true, pas de PAT serveur | Chaque développeur transmet son PAT | Par développeur |
| Token partagé (provisoire) | Déploiement rapide, identité de service unique acceptable | CIRCLECI_TOKEN sur le serveur, REQUIRE_REQUEST_TOKEN=false (désactivation explicite) | Aucun en-tête d'authentification nécessaire | Identité partagée unique |
Sécurité : L'authentification des requêtes est activée par défaut en mode distant. Le mode token partagé la désactive (
REQUIRE_REQUEST_TOKEN=false), permettant à chaque appelant d'agir en tant qu'identitéCIRCLECI_TOKENdu serveur sans informations d'identification. Activez-le uniquement sur un réseau de confiance totale, et préférez les tokens par utilisateur autrement. La terminaison TLS au niveau de l'ingress fournit le chiffrement, pas l'authentification.
1. Déployer le serveur
Les deux modes utilisent le mode HTTP distant (start=remote). Publiez le port 8000 (ou le port de votre choix).
Tokens par utilisateur (recommandé) :
docker run --rm -p 8000:8000 \
-e start=remote \
-e port=8000 \
-e REQUIRE_REQUEST_TOKEN=true \
circleci/mcp-server-circleci
Token partagé (provisoire) :
docker run --rm -p 8000:8000 \
-e start=remote \
-e port=8000 \
-e CIRCLECI_TOKEN=your-shared-circleci-pat \
-e REQUIRE_REQUEST_TOKEN=false \
circleci/mcp-server-circleci
Variables d'environnement :
| Variable | Description |
|---|---|
start=remote | Démarre le serveur MCP HTTP+SSE au lieu de stdio |
port | Port d'écoute à l'intérieur du conteneur (par défaut : 8000) |
REQUIRE_REQUEST_TOKEN | Rejeter les requêtes sans en-tête Authorization: Bearer ou Circle-Token. Activé par défaut ; définir REQUIRE_REQUEST_TOKEN=false pour autoriser les requêtes non authentifiées (mode token partagé) |
CIRCLECI_TOKEN | PAT de secours partagé pour toutes les requêtes lorsque les en-têtes par utilisateur ne sont pas envoyés |
CIRCLECI_BASE_URL | Facultatif — requis uniquement pour on-prem (par défaut : https://circleci.com) |
DISABLE_TELEMETRY=true | Désactiver l'exportation des métriques d'utilisation |
Le serveur accepte les tokens par requête via :
Authorization: Bearer <circleci-pat>Circle-Token: <circleci-pat>
Si un client envoie un token d'en-tête, il prend le pas sur CIRCLECI_TOKEN du serveur.
Les métriques de télémétrie enregistrées pendant une requête sont exportées en utilisant le même token que cette requête.
2. Configurer les clients
La plupart des clients MCP ne prennent en charge que les processus locaux (stdio). Utilisez mcp-remote, un pont stdio-vers-HTTP tiers, pour les connecter à votre serveur distant.
Schéma d'URL : Utilisez
http://localhost:8000/mcpavec--allow-httppour les tests locaux. En production, terminez TLS au niveau de votre ingress/load balancer et utilisezhttps://your-host/mcpsans--allow-http.
Windows : Évitez les espaces autour des deux-points dans les valeurs
--header. Mettez la valeur complèteBearer <token>dans une variable d'environnement.
Sécurité : Les exemples utilisent
npxpour plus de commodité. Pour la production ou les déploiements d'équipe, épinglez une version spécifique dans votre configuration MCP (par exemple[email protected]au lieu demcp-remote). N'utilisez pas de versions inférieures à0.1.16(CVE-2025-6514).
Configuration client : tokens par utilisateur
Chaque développeur transmet son propre token API personnel CircleCI à chaque requête :
{
"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}"
}
}
}
}
Remplacez http://localhost:8000/mcp par l’URL du serveur de votre équipe. Cursor et VS Code prennent en charge les invites ${input:...} ; les autres clients peuvent définir AUTH_HEADER directement.
Configuration du client : jeton partagé
Lorsque le serveur a défini CIRCLECI_TOKEN et est démarré avec REQUIRE_REQUEST_TOKEN=false (l’authentification par requête est activée par défaut et doit être explicitement désactivée), les clients n’ont pas besoin d’envoyer de jeton :
{
"mcpServers": {
"circleci-mcp-server-remote": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"http://localhost:8000/mcp",
"--allow-http"
]
}
}
}
Clients Claude Desktop et CLI
Créez un script wrapper (par exemple 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}"
Rendez-le exécutable (chmod +x circleci-remote-mcp.sh), puis référencez-le dans votre configuration MCP :
{
"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}"
Omettez --header et AUTH_HEADER lorsque vous utilisez un serveur à jeton partagé.
3. Vérifier le déploiement
# 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"}}}'
Démo
Regardez-le en action
Exemple : « Trouver le dernier pipeline en échec sur ma branche et obtenir les journaux » — consultez le wiki pour plus d’exemples.
https://github.com/user-attachments/assets/3c765985-8827-442a-a8dc-5069e01edb74
Détails des outils
analyze_diff
Analyse les diffs git par rapport aux règles cursor pour identifier les violations de règles.
Fournissez :
- Contenu du diff git (par exemple
git diff --cached,git diff HEAD) - Règles du dépôt depuis
.cursorrulesou.cursor/rules
Renvoie des rapports détaillés de violations avec des scores de confiance et des explications.
Utile pour :
- Les vérifications de qualité du code avant commit
- Assurer la cohérence avec les normes de codage de l’équipe
- Détecter les violations de règles avant la revue de code
config_helper
Aide aux tâches de configuration CircleCI en fournissant des conseils et une validation.
- Valide votre
.circleci/config.ymlpour les erreurs de syntaxe et sémantiques - Fournit des résultats de validation détaillés et des recommandations de configuration
- Exemple : « Valider ma configuration CircleCI »
create_prompt_template
Génère des modèles d’invite structurés pour les applications basées sur l’IA en fonction des exigences fonctionnelles.
- Transforme les exigences utilisateur en modèles d’invite optimisés
- Renvoie un modèle structuré et un schéma de contexte définissant les paramètres d’entrée requis
- Exemple : « Créer un modèle d’invite pour générer des histoires du soir par âge et par thème »
download_usage_api_data
Télécharge les données d’utilisation depuis l’API d’utilisation CircleCI pour une organisation donnée. Accepte des dates flexibles (par exemple, « mars 2025 » ou « le mois dernier »). Fonctionnalité cloud uniquement.
Option 1 : Démarrer un nouveau travail d’exportation en fournissant :
orgId,startDate,endDate(max 32 jours),outputDir
Option 2 : Vérifier/télécharger un travail d’exportation existant en fournissant :
orgId,jobId,outputDir
Renvoie un fichier CSV avec les données d’utilisation CircleCI pour la période spécifiée.
[!NOTE] Les données d’utilisation peuvent être transmises à l’outil
find_underused_resource_classespour une analyse d’optimisation des coûts.
find_flaky_tests
Identifie les tests instables dans votre projet CircleCI en analysant l’historique d’exécution des tests. Exploite la fonctionnalité de détection des tests instables de CircleCI.
Cet outil peut être utilisé de trois manières :
-
En utilisant le slug du projet (recommandé) :
- Utilisez d’abord
list_followed_projectspour obtenir vos projets, puis : - Exemple : « Obtenir les tests instables pour mon-projet »
- Utilisez d’abord
-
En utilisant l’URL du projet CircleCI :
- Exemple : « Trouver les tests instables dans https://app.circleci.com/pipelines/github/org/repo »
-
En utilisant le contexte du projet local :
- Fonctionne depuis votre espace de travail local en fournissant la racine de l’espace de travail et l’URL distante git
- Exemple : « Trouver les tests instables dans mon projet actuel »
Modes de sortie :
- Texte (par défaut) : Renvoie les détails des tests instables au format texte
- Fichier (nécessite la variable d’environnement
FILE_OUTPUT_DIRECTORY) : Crée un répertoire avec les détails des tests instables
find_underused_resource_classes
Analyse un fichier CSV de données d’utilisation CircleCI pour trouver les travaux dont l’utilisation moyenne ou maximale du CPU/RAM est inférieure à un seuil donné (par défaut : 40 %).
Fournissez un fichier CSV obtenu depuis download_usage_api_data.
Renvoie une liste markdown des travaux sous-utilisés organisée par projet et workflow — utile pour identifier les opportunités d’optimisation des coûts.
get_build_failure_logs
Récupère les journaux d’échec détaillés des builds CircleCI. Cet outil peut être utilisé de trois manières :
-
En utilisant le slug du projet et la branche (recommandé) :
- Utilisez d’abord
list_followed_projectspour obtenir vos projets, puis : - Exemple : « Obtenir les échecs de build pour mon-projet sur la branche principale »
- Utilisez d’abord
-
En utilisant les URL CircleCI :
- Fournissez directement une URL de job en échec ou une URL de pipeline
- Exemple : « Obtenir les journaux de https://app.circleci.com/pipelines/github/org/repo/123 »
-
En utilisant le contexte du projet local :
- Fonctionne depuis votre espace de travail local en fournissant la racine de l’espace de travail, l’URL distante git et le nom de la branche
- Exemple : « Trouver le dernier pipeline en échec sur ma branche actuelle »
L’outil renvoie des journaux formatés incluant :
- Les noms des jobs
- Les détails d’exécution étape par étape
- Les messages d’échec et le contexte
get_job_test_results
Récupère les métadonnées de test pour les jobs CircleCI, vous permettant d’analyser les résultats des tests sans quitter votre IDE. Cet outil peut être utilisé de trois manières :
-
En utilisant le slug du projet et la branche (recommandé) :
- Exemple : « Obtenir les résultats des tests pour mon-projet sur la branche principale »
-
En utilisant l’URL CircleCI :
- URL du job :
https://app.circleci.com/pipelines/github/org/repo/123/workflows/abc-def/jobs/789 - URL du workflow :
https://app.circleci.com/pipelines/github/org/repo/123/workflows/abc-def - URL du pipeline :
https://app.circleci.com/pipelines/github/org/repo/123
- URL du job :
-
En utilisant le contexte du projet local :
- Fonctionne depuis votre espace de travail local en fournissant la racine de l’espace de travail, l’URL distante git et le nom de la branche
L’outil renvoie :
- Un résumé de tous les tests (total, réussis, échoués)
- Des informations détaillées sur les tests échoués : nom, classe, fichier, message d’erreur, durée
- La liste des tests réussis avec leur durée
- Filtrage par résultat de test
[!NOTE] Les métadonnées de test doivent être configurées dans votre configuration CircleCI. Consultez Collecter les données de test pour les instructions de configuration.
get_latest_pipeline_status
Récupère le statut du dernier pipeline pour une branche donnée. Cet outil peut être utilisé de trois manières :
-
En utilisant le slug du projet et la branche (recommandé) :
- Exemple : « Obtenir le statut du dernier pipeline pour mon-projet sur la branche principale »
-
En utilisant l’URL du projet CircleCI :
- Exemple : « Obtenir le statut du dernier pipeline pour https://app.circleci.com/pipelines/github/org/repo »
-
En utilisant le contexte du projet local :
- Fonctionne depuis votre espace de travail local en fournissant la racine de l’espace de travail, l’URL distante git et le nom de la branche
Exemple de sortie :
---
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
Récupère la liste des artefacts produits par un job CircleCI. Cet outil peut être utilisé de trois manières :
-
En utilisant le slug du projet et la branche (recommandé) :
- Utilisez d’abord
list_followed_projectspour obtenir vos projets, puis : - Exemple : « Lister les artefacts pour mon-projet sur la branche principale »
- Utilisez d’abord
-
En utilisant l’URL CircleCI :
- URL du job :
https://app.circleci.com/pipelines/gh/organization/project/123/workflows/abc-def/jobs/789 - URL du workflow :
https://app.circleci.com/pipelines/gh/organization/project/123/workflows/abc-def - URL du pipeline :
https://app.circleci.com/pipelines/gh/organization/project/123
- URL du job :
-
En utilisant le contexte du projet local :
- Fonctionne depuis votre espace de travail local en fournissant la racine de l’espace de travail, l’URL distante git et le nom de la branche
Utile pour :
- Trouver les URL de téléchargement des artefacts de build (binaires, rapports, journaux)
- Vérifier quels artefacts ont été produits par une exécution de pipeline
list_component_versions
Liste toutes les versions d’un composant CircleCI spécifique dans un environnement. Inclut le statut de déploiement, les informations de commit et les horodatages.
L’outil vous demandera de sélectionner le composant et l’environnement s’ils ne sont pas fournis.
Utile pour :
- Identifier quelle version est actuellement en ligne
- Sélectionner les versions cibles pour les opérations de rollback
- Obtenir les détails de déploiement (pipeline, workflow, job)
list_followed_projects
Liste tous les projets que l’utilisateur suit sur CircleCI.
- Affiche tous les projets auxquels vous avez accès avec leur
projectSlug - Exemple : « Lister mes projets CircleCI »
Exemple de sortie :
Projects followed:
1. my-project (projectSlug: gh/organization/my-project)
2. another-project (projectSlug: gh/organization/another-project)
[!NOTE] Le
projectSlug(et non le nom du projet) est requis pour de nombreux autres outils CircleCI.
recommend_prompt_template_tests
Génère des cas de test pour les modèles d’invite afin de garantir qu’ils produisent les résultats attendus.
- Crée des scénarios de test diversifiés basés sur votre modèle d’invite et le schéma de contexte
- Renvoie un tableau de cas de test recommandés avec diverses combinaisons de paramètres
- Exemple : « Générer des tests pour mon modèle d’invite d’histoire du soir »
rerun_workflow
Relance un workflow depuis son début ou depuis le job en échec.
Renvoie l’ID du workflow nouvellement créé et un lien pour le surveiller.
run_evaluation_tests
Exécute des tests d’évaluation (également appelés « Tests d’invite ») sur un pipeline CircleCI. Génère une configuration CircleCI appropriée et déclenche un pipeline en l’utilisant.
Cet outil peut être utilisé de trois manières :
-
En utilisant le slug du projet et la branche (recommandé) :
- Utilisez d’abord
list_followed_projectspour obtenir vos projets, puis : - Exemple : « Exécuter les tests d’évaluation pour mon-projet sur la branche principale »
- Utilisez d’abord
-
En utilisant l’URL CircleCI :
- URL du projet, URL du pipeline, URL du workflow ou URL du job
- Exemple : « Exécuter les tests d’évaluation pour https://app.circleci.com/pipelines/gh/organization/project/123 »
-
En utilisant le contexte du projet local :
- Fonctionne depuis votre espace de travail local en fournissant la racine de l’espace de travail, l’URL distante git et le nom de la branche
L’outil accepte les fichiers de modèle d’invite et renvoie une URL pour surveiller le pipeline déclenché.
[!NOTE] Si le projet a plusieurs définitions de pipeline, l’outil renverra une liste des pipelines disponibles parmi lesquels vous pourrez choisir.
run_pipeline
Déclenche l’exécution d’un pipeline. Cet outil peut être utilisé de trois manières :
-
En utilisant le slug du projet et la branche (recommandé) :
- Exemple : « Exécuter le pipeline pour mon-projet sur la branche principale »
-
En utilisant l’URL CircleCI :
- URL du pipeline, URL du workflow, URL du job ou URL du projet avec la branche
- Exemple : « Exécuter le pipeline pour https://app.circleci.com/pipelines/github/org/repo/123 »
-
En utilisant le contexte du projet local :
- Fonctionne depuis votre espace de travail local en fournissant la racine de l’espace de travail, l’URL distante git et le nom de la branche
L’outil renvoie un lien pour surveiller l’exécution du pipeline.
run_rollback_pipeline
Déclenche un rollback pour un projet CircleCI. L'outil vous guide de manière interactive à travers les étapes suivantes :
- Sélection du projet — liste les projets suivis parmi lesquels choisir
- Sélection de l'environnement — liste les environnements disponibles (sélection automatique s'il n'y en a qu'un)
- Sélection du composant — liste les composants disponibles (sélection automatique s'il n'y en a qu'un)
- Sélection de la version — affiche les versions disponibles ; vous sélectionnez la cible du rollback
- Détection du mode de rollback — vérifie si un pipeline de rollback est configuré
- Exécuter le rollback — deux options :
- Rollback par pipeline : déclenche le pipeline de rollback
- Réexécution du workflow : réexécute un workflow précédent en utilisant son ID de workflow
- Confirmation — résume et confirme avant l'exécution
Dépannage
Correctifs rapides
Problèmes les plus courants :
-
Vider les caches des paquets :
npx clear-npx-cache npm cache clean --force -
Forcer la dernière version : Ajoutez
@latestà votre configuration :"args": ["-y", "@circleci/mcp-server-circleci@latest"] -
Redémarrez complètement votre IDE (pas seulement recharger la fenêtre)
Problèmes d'authentification
- Erreurs de jeton invalide : Vérifiez votre
CIRCLECI_TOKENdans Jetons d'API personnels - Erreurs de permission : Assurez-vous que le jeton a un accès en lecture à vos projets
- Variables d'environnement non chargées : Testez avec
echo $CIRCLECI_TOKEN(Mac/Linux) ouecho %CIRCLECI_TOKEN%(Windows)
Problèmes de connexion et de réseau
- URL de base : Confirmez que
CIRCLECI_BASE_URLesthttps://circleci.com - Réseaux d'entreprise : Configurez les paramètres de proxy npm si vous êtes derrière un pare-feu
- Blocage par pare-feu : Vérifiez si un logiciel de sécurité bloque les téléchargements de paquets
Configuration système requise
- Version de Node.js : Assurez-vous qu'elle est >= 18.0.0 avec
node --version - Mettre à jour Node.js : Envisagez la dernière version LTS en cas de problèmes de compatibilité
- Gestionnaire de paquets : Vérifiez que npm/pnpm fonctionne :
npm --version
Problèmes spécifiques à l'IDE
- Emplacement du fichier de configuration : Vérifiez le chemin pour votre système d'exploitation
- Erreurs de syntaxe : Validez la syntaxe JSON dans votre fichier de configuration
- Journaux de la console : Consultez la console développeur de l'IDE pour des erreurs spécifiques
- Essayez un autre IDE : Testez dans un autre éditeur pris en charge pour isoler le problème
Problèmes de processus
Processus bloqués — tuez les processus MCP existants :
# Mac/Linux:
pkill -f "mcp-server-circleci"
# Windows:
taskkill /f /im node.exe
Conflits de port : Redémarrez votre IDE si la connexion semble bloquée.
Débogage avancé
- Tester le paquet directement :
npx @circleci/mcp-server-circleci@latest --help - Journalisation verbeuse :
DEBUG=* npx @circleci/mcp-server-circleci@latest - Solution de repli Docker : Essayez l'installation Docker si npx échoue systématiquement
Besoin d'aide supplémentaire ?
- Consultez les Problèmes GitHub pour des problèmes similaires
- Indiquez votre système d'exploitation, la version de Node et votre IDE lors du signalement
- Partagez les messages d'erreur pertinents de la console de l'IDE
Télémétrie
Le serveur prend en charge les métriques OpenTelemetry pour le suivi de l'utilisation des outils. Les métriques sont exportées sauf si vous définissez DISABLE_TELEMETRY=true. Sur les déploiements distants, les métriques utilisent le même jeton que la requête (PAT par utilisateur ou PAT de serveur partagé).
| Métrique | Description |
|---|---|
circleci.mcp.tool.invocations | Nombre d'invocations de l'outil |
circleci.mcp.tool.duration_ms | Temps d'exécution en ms |
circleci.mcp.tool.errors | Nombre d'erreurs |
Développement
Pour commencer
-
Cloner le dépôt :
git clone https://github.com/CircleCI-Public/mcp-server-circleci.git cd mcp-server-circleci -
Installer les dépendances :
pnpm install -
Construire le projet :
pnpm build
Construction du conteneur Docker
Vous pouvez construire le conteneur Docker localement en utilisant :
docker build -t circleci:mcp-server-circleci .
Cela créera une image Docker étiquetée circleci:mcp-server-circleci que vous pourrez utiliser avec n'importe quel client MCP.
Mode stdio local (développeur unique, jeton sur le client) :
docker run --rm -i \
-e CIRCLECI_TOKEN=your-circleci-token \
-e CIRCLECI_BASE_URL=https://circleci.com \
circleci/mcp-server-circleci
Mode distant (serveur centralisé pour une équipe) : voir Serveur MCP distant auto-géré.
Développement avec l'inspecteur MCP
Le moyen le plus simple d'itérer sur le serveur MCP est d'utiliser l'inspecteur MCP. Vous pouvez en savoir plus sur l'inspecteur MCP à l'adresse https://modelcontextprotocol.io/docs/tools/inspector
-
Démarrer le serveur de développement :
pnpm watch # Keep this running in one terminal -
Dans un terminal séparé, lancer l'inspecteur :
pnpm inspector -
Configurer l'environnement :
- Ajoutez votre
CIRCLECI_TOKENà la section Variables d'environnement dans l'interface de l'inspecteur - Le jeton doit avoir un accès en lecture à vos projets CircleCI
- Définissez éventuellement votre URL de base CircleCI (par défaut
https://circleci.com)
- Ajoutez votre
Tests
-
Exécuter la suite de tests :
pnpm test -
Exécuter les tests en mode surveillance pendant le développement :
pnpm test:watch
Pour des directives de contribution plus détaillées, voir CONTRIBUTING.md