CircleCI MCP Server

officiel

Permettre aux agents IA de corriger les échecs de build depuis CircleCI.

Documentation

Serveur MCP CircleCI

License: Apache 2.0 CircleCI npm

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

OutilDescription
analyze_diffAnalyser les diffs git par rapport aux règles cursor pour détecter les violations
config_helperValider et obtenir des conseils pour votre configuration CircleCI
create_prompt_templateGénérer des modèles de prompts structurés pour les applications d'IA
download_usage_api_dataTélécharger les données d'utilisation depuis l'API d'utilisation CircleCI
find_flaky_testsIdentifier les tests instables en analysant l'historique d'exécution des tests
find_underused_resource_classesTrouver les jobs avec des ressources de calcul sous-utilisées
get_build_failure_logsRécupérer les journaux d'échec détaillés des builds CircleCI
get_job_test_resultsRécupérer les métadonnées et résultats de test pour les jobs CircleCI
get_latest_pipeline_statusObtenir le statut du dernier pipeline pour une branche
list_artifactsLister les artefacts produits par un job CircleCI
list_component_versionsLister toutes les versions d'un composant CircleCI
list_followed_projectsLister tous les projets CircleCI que vous suivez
recommend_prompt_template_testsGénérer des cas de test pour les modèles de prompts
rerun_workflowRelancer un workflow depuis le début ou depuis le job en échec
run_evaluation_testsExécuter des tests d'évaluation sur un pipeline CircleCI
run_pipelineDéclencher l'exécution d'un pipeline
run_rollback_pipelineDé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 :

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_URL est facultatif — requis uniquement pour les clients on-prem. MAX_MCP_OUTPUT_LENGTH est 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 :

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 :

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 :

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 :

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 :

  1. Accédez à l'interface de configuration MCP
  2. Choisissez le symbole +
  3. Sélectionnez la portée : global ou local
  4. Entrez un nom (par ex. circleci-remote-mcp)
  5. Sélectionnez le protocole de transport : stdio
  6. Entrez le chemin de la commande vers votre script
  7. 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

ModeQuand l'utiliserConfiguration serveurConfiguration clientPiste d'audit CircleCI
Tokens par utilisateur (recommandé)Équipes avec des tokens API personnels adossés à SSOREQUIRE_REQUEST_TOKEN=true, pas de PAT serveurChaque développeur transmet son PATPar développeur
Token partagé (provisoire)Déploiement rapide, identité de service unique acceptableCIRCLECI_TOKEN sur le serveur, REQUIRE_REQUEST_TOKEN=false (désactivation explicite)Aucun en-tête d'authentification nécessaireIdentité 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_TOKEN du 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 :

VariableDescription
start=remoteDémarre le serveur MCP HTTP+SSE au lieu de stdio
portPort d'écoute à l'intérieur du conteneur (par défaut : 8000)
REQUIRE_REQUEST_TOKENRejeter 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_TOKENPAT de secours partagé pour toutes les requêtes lorsque les en-têtes par utilisateur ne sont pas envoyés
CIRCLECI_BASE_URLFacultatif — requis uniquement pour on-prem (par défaut : https://circleci.com)
DISABLE_TELEMETRY=trueDé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/mcp avec --allow-http pour les tests locaux. En production, terminez TLS au niveau de votre ingress/load balancer et utilisez https://your-host/mcp sans --allow-http.

Windows : Évitez les espaces autour des deux-points dans les valeurs --header. Mettez la valeur complète Bearer <token> dans une variable d'environnement.

Sécurité : Les exemples utilisent npx pour 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 de mcp-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 .cursorrules ou .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.yml pour 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_classes pour 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 :

  1. En utilisant le slug du projet (recommandé) :

    • Utilisez d’abord list_followed_projects pour obtenir vos projets, puis :
    • Exemple : « Obtenir les tests instables pour mon-projet »
  2. En utilisant l’URL du projet CircleCI :

  3. 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 :

  1. En utilisant le slug du projet et la branche (recommandé) :

    • Utilisez d’abord list_followed_projects pour obtenir vos projets, puis :
    • Exemple : « Obtenir les échecs de build pour mon-projet sur la branche principale »
  2. En utilisant les URL CircleCI :

  3. 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 :

  1. En utilisant le slug du projet et la branche (recommandé) :

    • Exemple : « Obtenir les résultats des tests pour mon-projet sur la branche principale »
  2. 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
  3. 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 :

  1. En utilisant le slug du projet et la branche (recommandé) :

    • Exemple : « Obtenir le statut du dernier pipeline pour mon-projet sur la branche principale »
  2. En utilisant l’URL du projet CircleCI :

  3. 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 :

  1. En utilisant le slug du projet et la branche (recommandé) :

    • Utilisez d’abord list_followed_projects pour obtenir vos projets, puis :
    • Exemple : « Lister les artefacts pour mon-projet sur la branche principale »
  2. 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
  3. 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 :

  1. En utilisant le slug du projet et la branche (recommandé) :

    • Utilisez d’abord list_followed_projects pour obtenir vos projets, puis :
    • Exemple : « Exécuter les tests d’évaluation pour mon-projet sur la branche principale »
  2. En utilisant l’URL CircleCI :

  3. 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 :

  1. En utilisant le slug du projet et la branche (recommandé) :

    • Exemple : « Exécuter le pipeline pour mon-projet sur la branche principale »
  2. En utilisant l’URL CircleCI :

  3. 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 :
  1. Sélection du projet — liste les projets suivis parmi lesquels choisir
  2. Sélection de l'environnement — liste les environnements disponibles (sélection automatique s'il n'y en a qu'un)
  3. Sélection du composant — liste les composants disponibles (sélection automatique s'il n'y en a qu'un)
  4. Sélection de la version — affiche les versions disponibles ; vous sélectionnez la cible du rollback
  5. Détection du mode de rollback — vérifie si un pipeline de rollback est configuré
  6. 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
  7. Confirmation — résume et confirme avant l'exécution

Dépannage

Correctifs rapides

Problèmes les plus courants :

  1. Vider les caches des paquets :

    npx clear-npx-cache
    npm cache clean --force
    
  2. Forcer la dernière version : Ajoutez @latest à votre configuration :

    "args": ["-y", "@circleci/mcp-server-circleci@latest"]
    
  3. Redémarrez complètement votre IDE (pas seulement recharger la fenêtre)

Problèmes d'authentification
  • Erreurs de jeton invalide : Vérifiez votre CIRCLECI_TOKEN dans 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) ou echo %CIRCLECI_TOKEN% (Windows)
Problèmes de connexion et de réseau
  • URL de base : Confirmez que CIRCLECI_BASE_URL est https://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 ?

  1. Consultez les Problèmes GitHub pour des problèmes similaires
  2. Indiquez votre système d'exploitation, la version de Node et votre IDE lors du signalement
  3. 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étriqueDescription
circleci.mcp.tool.invocationsNombre d'invocations de l'outil
circleci.mcp.tool.duration_msTemps d'exécution en ms
circleci.mcp.tool.errorsNombre d'erreurs

Développement

Pour commencer

  1. Cloner le dépôt :

    git clone https://github.com/CircleCI-Public/mcp-server-circleci.git
    cd mcp-server-circleci
    
  2. Installer les dépendances :

    pnpm install
    
  3. 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

  1. Démarrer le serveur de développement :

    pnpm watch # Keep this running in one terminal
    
  2. Dans un terminal séparé, lancer l'inspecteur :

    pnpm inspector
    
  3. 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)

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