Servidor MCP de CircleCI

El Protocolo de Contexto de Modelo (MCP) es un nuevo protocolo estandarizado para gestionar el contexto entre grandes modelos de lenguaje (LLM) y sistemas externos. En este repositorio, ofrecemos un servidor MCP para CircleCI .

Esto le permite usar Cursor IDE, Windsurf, Copilot o cualquier cliente compatible con MCP para usar lenguaje natural y lograr cosas con CircleCI, por ejemplo:

• Find the latest failed pipeline on my branch and get logshttps://github.com/CircleCI-Public/mcp-server-circleci/wiki#circleci-mcp-server-with-cursor-ide

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

Requisitos

• Token de la API de CircleCI: puedes generar uno a través de CircleCI. Obtén más información o haz clic aquí para acceder rápidamente.

Para la instalación de NPX:

• Gestor de paquetes pnpm: Más información

• Node.js >= v18.0.0

Para la instalación de Docker:

• Docker - Más información

Instalación

Cursor

Uso de NPX

Agregue lo siguiente a la configuración MCP de su cursor:

Usando Docker

Agregue lo siguiente a la configuración MCP de su cursor:

Código VS

Uso de NPX

Para instalar CircleCI MCP Server para VS Code en .vscode/mcp.json :

Usando Docker

Para instalar CircleCI MCP Server para VS Code en .vscode/mcp.json usando Docker:

Escritorio de Claude

Uso de NPX

Agregue lo siguiente a su claude_desktop_config.json:

Usando Docker

Agregue lo siguiente a su claude_desktop_config.json:

Para encontrar/crear este archivo, primero abra la configuración de escritorio de Claude. Luego, haga clic en "Desarrollador" en la barra izquierda del panel de Configuración y, a continuación, en "Editar configuración".

Esto creará un archivo de configuración en:

• macOS: ~/Biblioteca/Soporte de aplicaciones/Claude/claude_desktop_config.json

• Ventanas: %APPDATA%\Claude\claude_desktop_config.json

Consulte la guía a continuación para obtener más información sobre el uso de servidores MCP con Claude Desktop: https://modelcontextprotocol.io/quickstart/user

Claude Code

Uso de NPX

Después de instalar Claude Code, ejecute el siguiente comando:

Usando Docker

Después de instalar Claude Code, ejecute el siguiente comando:

Consulte la guía a continuación para obtener más información sobre el uso de servidores MCP con Claude Code: https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/tutorials#set-up-model-context-protocol-mcp

Windsurf

Uso de NPX

Agregue lo siguiente a su windsurf mcp_config.json:

Usando Docker

Agregue lo siguiente a su windsurf mcp_config.json:

Consulte la guía a continuación para obtener más información sobre el uso de servidores MCP con Windsurf: https://docs.windsurf.com/windsurf/mcp

Instalación mediante herrería

Para instalar CircleCI MCP Server para Claude Desktop automáticamente a través de Smithery :

Características

Herramientas compatibles

• get_build_failure_logs

  Recupera registros detallados de errores de las compilaciones de CircleCI. Esta herramienta se puede utilizar de tres maneras:

  1. Uso de Project Slug y Branch (flujo de trabajo recomendado):

     • Primero, enumera tus proyectos disponibles:

       • Utilice la herramienta list_followed_projects para obtener sus proyectos

       • Ejemplo: "Enumerar mis proyectos de CircleCI"

       • A continuación, seleccione el proyecto que tenga un projectSlug asociado.

       • Ejemplo: "Usemos mi-proyecto"

     • Luego, solicita recuperar los registros de errores de compilación para una rama específica:

       • Ejemplo: "Obtener errores de compilación para mi proyecto en la rama principal"

  2. Uso de las URL de CircleCI:

     • Proporcione una URL de trabajo fallido o una URL de canalización directamente

     • Ejemplo: "Obtener registros de https://app.circleci.com/pipelines/github/org/repo/123 "

  3. Uso del contexto del proyecto local:

     • Trabaja desde su espacio de trabajo local proporcionando:

       • Ruta raíz del espacio de trabajo

       • URL remota de Git

       • Nombre de la sucursal

     • Ejemplo: "Buscar el último pipeline fallido en mi rama actual"

  La herramienta devuelve registros formateados que incluyen:

  • Nombres de trabajos

  • Detalles de ejecución paso a paso

  • Mensajes de error y contexto

  Esto es particularmente útil para:

  • Depuración de compilaciones fallidas

  • Análisis de fallos de pruebas

  • Investigación de problemas de implementación

  • Acceso rápido a los registros de compilación sin salir de su IDE

• find_flaky_tests

  Identifica pruebas inestables en tu proyecto CircleCI analizando el historial de ejecución de pruebas. Esto aprovecha la función de detección de pruebas inestables que se describe aquí: https://circleci.com/blog/introducing-test-insights-with-flaky-test-detection/#flaky-test-detection

  Esta herramienta se puede utilizar de tres maneras:

  1. Uso de Project Slug (flujo de trabajo recomendado):

     • Primero, enumera tus proyectos disponibles:

       • Utilice la herramienta list_followed_projects para obtener sus proyectos

       • Ejemplo: "Enumerar mis proyectos de CircleCI"

       • A continuación, seleccione el proyecto que tenga un projectSlug asociado.

       • Ejemplo: "Usemos mi-proyecto"

     • Luego pide recuperar las pruebas fallidas:

       • Ejemplo: "Obtener pruebas inestables para mi proyecto"

  2. Usando la URL del proyecto CircleCI:

     • Proporcione la URL del proyecto directamente desde CircleCI

     • Ejemplo: "Encuentra pruebas inestables en https://app.circleci.com/pipelines/github/org/repo "

  3. Uso del contexto del proyecto local:

     • Trabaja desde su espacio de trabajo local proporcionando:

       • Ruta raíz del espacio de trabajo

       • URL remota de Git

     • Ejemplo: "Encontrar pruebas defectuosas en mi proyecto actual"

  La herramienta devuelve información detallada sobre pruebas inestables, que incluye:

  • Nombres de prueba y ubicaciones de archivos

  • Mensajes y contextos de fallo

  Esto le ayudará a:

  • Identifique pruebas no confiables en su conjunto de pruebas

  • Obtenga un contexto detallado sobre los fallos de las pruebas

  • Tome decisiones basadas en datos sobre mejoras en las pruebas

• get_latest_pipeline_status

  Recupera el estado del último pipeline de una rama determinada. Esta herramienta se puede utilizar de tres maneras:

  1. Uso de Project Slug y Branch (flujo de trabajo recomendado):

     • Primero, enumera tus proyectos disponibles:

       • Utilice la herramienta list_followed_projects para obtener sus proyectos

       • Ejemplo: "Enumerar mis proyectos de CircleCI"

       • A continuación, seleccione el proyecto que tenga un projectSlug asociado.

       • Ejemplo: "Usemos mi-proyecto"

     • A continuación, solicita recuperar el último estado del pipeline para una rama específica:

       • Ejemplo: "Obtener el estado del último pipeline de mi proyecto en la rama principal"

  2. Usando la URL del proyecto CircleCI:

     • Proporcione la URL del proyecto directamente desde CircleCI

     • Ejemplo: "Obtener el estado del último pipeline para https://app.circleci.com/pipelines/github/org/repo "

  3. Uso del contexto del proyecto local:

     • Trabaja desde su espacio de trabajo local proporcionando:

       • Ruta raíz del espacio de trabajo

       • URL remota de Git

       • Nombre de la sucursal

     • Ejemplo: "Obtener el estado del último pipeline de mi proyecto actual"

  La herramienta devuelve un estado formateado del último pipeline:

  • Nombres de flujos de trabajo y su estado actual

  • Duración de cada flujo de trabajo

  • Marcas de tiempo de creación y finalización

  • Estado general del oleoducto

  Ejemplo de salida:

  --- 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

  Esto es particularmente útil para:

  • Comprobación del estado del último pipeline

  • Obtener el estado del último pipeline para una sucursal específica

  • Comprobación rápida del estado del último pipeline sin salir del IDE

• get_job_test_results

  Recupera metadatos de pruebas para trabajos de CircleCI, lo que permite analizar los resultados sin salir del IDE. Esta herramienta se puede usar de tres maneras:

  1. Uso de Project Slug y Branch (flujo de trabajo recomendado):

     • Primero, enumera tus proyectos disponibles:

       • Utilice la herramienta list_followed_projects para obtener sus proyectos

       • Ejemplo: "Enumerar mis proyectos de CircleCI"

       • A continuación, seleccione el proyecto que tenga un projectSlug asociado.

       • Ejemplo: "Usemos mi-proyecto"

     • Luego solicita recuperar los resultados de la prueba para una rama específica:

       • Ejemplo: "Obtener resultados de pruebas para mi-proyecto en la rama principal"

  2. Usando la URL de CircleCI:

     • Proporcione una URL de CircleCI en cualquiera de estos formatos:

       • URL del trabajo: " https://app.circleci.com/pipelines/github/org/repo/123/workflows/abc-def/jobs/789 "

       • URL del flujo de trabajo: " https://app.circleci.com/pipelines/github/org/repo/123/workflows/abc-def "

       • URL de la canalización: " https://app.circleci.com/pipelines/github/org/repo/123 "

     • Ejemplo: "Obtener resultados de la prueba para https://app.circleci.com/pipelines/github/org/repo/123/workflows/abc-def "

  3. Uso del contexto del proyecto local:

     • Trabaja desde su espacio de trabajo local proporcionando:

       • Ruta raíz del espacio de trabajo

       • URL remota de Git

       • Nombre de la sucursal

     • Ejemplo: "Obtener resultados de pruebas para mi proyecto actual en la rama principal"

  La herramienta devuelve información detallada de los resultados de la prueba:

  • Resumen de todas las pruebas (total, exitosas, fallidas)

  • Información detallada sobre las pruebas fallidas, incluyendo:

    • Nombre y clase de la prueba

    • Ubicación del archivo

    • Mensajes de error

    • Duración del tiempo de ejecución

  • Lista de pruebas exitosas con información de tiempo

  • Filtrar por resultado de pruebas

  Esto es particularmente útil para:

  • Análisis rápido de fallas de pruebas sin visitar la interfaz web de CircleCI

  • Identificación de patrones en fallos de pruebas

  • Encontrar pruebas lentas que podrían necesitar optimización

  • Comprobación de la cobertura de pruebas en todo el proyecto

  • Solución de problemas de pruebas inestables

  Nota: La herramienta requiere que los metadatos de prueba estén configurados correctamente en la configuración de CircleCI. Para obtener más información sobre cómo configurar la recopilación de metadatos de prueba, consulte: https://circleci.com/docs/collect-test-data/

• config_helper

  Asiste en las tareas de configuración de CircleCI proporcionando orientación y validación. Esta herramienta le ayuda a:

  1. Validar la configuración de CircleCI:

     • Comprueba su .circleci/config.yml en busca de errores de sintaxis y semántica

     • Ejemplo: "Validar mi configuración de CircleCI"

  La herramienta proporciona:

  • Resultados detallados de la validación

  • Recomendaciones de configuración

  Esto le ayudará a:

  • Detectar errores de configuración antes de enviar

  • Aprenda las mejores prácticas de configuración de CircleCI

  • Solucionar problemas de configuración

  • Implementar correctamente las funciones de CircleCI

• create_prompt_template

  Ayuda a generar plantillas de indicaciones estructuradas para aplicaciones con IA según los requisitos de las funciones. Esta herramienta:

  1. Convierte los requisitos de las funciones en indicaciones estructuradas:

     • Transforma los requisitos del usuario en plantillas de indicaciones optimizadas

     • Ejemplo: "Crear una plantilla de indicaciones para generar cuentos para dormir por edad y tema"

  La herramienta proporciona:

  • Una plantilla de mensaje estructurado

  • Un esquema de contexto que define los parámetros de entrada requeridos

  Esto le ayudará a:

  • Cree indicaciones efectivas para aplicaciones de IA

  • Estandarizar los parámetros de entrada para obtener resultados consistentes

  • Cree funciones robustas impulsadas por IA

• recommend_prompt_template_tests

  Genera casos de prueba para plantillas de indicaciones para garantizar que produzcan los resultados esperados. Esta herramienta:

  1. Proporciona casos de prueba para plantillas de indicaciones:

     • Crea diversos escenarios de prueba basados en su plantilla de solicitud y esquema de contexto

     • Ejemplo: "Generar pruebas para mi plantilla de indicaciones para el cuento antes de dormir"

  La herramienta proporciona:

  • Una serie de casos de prueba recomendados

  • Varias combinaciones de parámetros para probar la robustez de la plantilla

  Esto le ayudará a:

  • Validar la funcionalidad de la plantilla de solicitud

  • Asegúrese de que las respuestas de IA sean consistentes en todas las entradas

  • Identificar casos extremos y problemas potenciales

  • Mejorar la calidad general de las aplicaciones de IA

• list_followed_projects

  Enumera todos los proyectos que el usuario sigue en CircleCI. Esta herramienta:

  1. Recupera y muestra proyectos:

     • Muestra todos los proyectos a los que el usuario tiene acceso y está siguiendo

     • Proporciona el nombre del proyecto y el projectSlug para cada entrada

     • Ejemplo: "Enumerar mis proyectos de CircleCI"

  La herramienta devuelve una lista formateada de proyectos, ejemplo de salida:

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

  Esto es particularmente útil para:

  • Identificar qué proyectos de CircleCI están disponibles para usted

  • Obtener el projectSlug necesario para otras herramientas de CircleCI

  • Seleccionar un proyecto para operaciones posteriores

  Nota: El projectSlug (no el nombre del proyecto) es necesario para muchas otras herramientas de CircleCI y se utilizará para aquellas llamadas de herramientas después de seleccionar un proyecto.

• run_pipeline

  Activa la ejecución de una canalización. Esta herramienta se puede usar de tres maneras:

  1. Uso de Project Slug y Branch (flujo de trabajo recomendado):

     • Primero, enumera tus proyectos disponibles:

       • Utilice la herramienta list_followed_projects para obtener sus proyectos

       • Ejemplo: "Enumerar mis proyectos de CircleCI"

       • A continuación, seleccione el proyecto que tenga un projectSlug asociado.

       • Ejemplo: "Usemos mi-proyecto"

     • Luego solicita ejecutar el pipeline para una rama específica:

       • Ejemplo: "Ejecutar la canalización para mi-proyecto en la rama principal"

  2. Usando la URL de CircleCI:

     • Proporcione una URL de CircleCI en cualquiera de estos formatos:

       • URL del trabajo: " https://app.circleci.com/pipelines/github/org/repo/123/workflows/abc-def/jobs/789 "

       • URL del flujo de trabajo: " https://app.circleci.com/pipelines/github/org/repo/123/workflows/abc-def "

       • URL de la canalización: " https://app.circleci.com/pipelines/github/org/repo/123 "

       • URL del proyecto con rama: " https://app.circleci.com/projects/github/org/repo?branch=main "

     • Ejemplo: "Ejecutar la canalización para https://app.circleci.com/pipelines/github/org/repo/123/workflows/abc-def "

  3. Uso del contexto del proyecto local:

     • Trabaja desde su espacio de trabajo local proporcionando:

       • Ruta raíz del espacio de trabajo

       • URL remota de Git

       • Nombre de la sucursal

     • Ejemplo: "Ejecutar la canalización de mi proyecto actual en la rama principal"

  La herramienta devuelve un enlace para monitorear la ejecución del pipeline.

  Esto es particularmente útil para:

  • Ejecución rápida de pipelines sin necesidad de visitar la interfaz web de CircleCI

  • Ejecución de tuberías desde una rama específica

Desarrollo

Empezando

1. Clonar el repositorio:

   git clone https://github.com/CircleCI-Public/mcp-server-circleci.git cd mcp-server-circleci

2. Instalar dependencias:

   pnpm install

3. Construir el proyecto:

   pnpm build

Construcción de un contenedor Docker

Puedes construir el contenedor Docker localmente usando:

Esto creará una imagen de Docker etiquetada como circleci:mcp-server-circleci que puedes usar con cualquier cliente MCP.

Para ejecutar el contenedor:

Desarrollo con MCP Inspector

La forma más sencilla de iterar en el servidor MCP es mediante el inspector MCP. Puede obtener más información sobre el inspector MCP en https://modelcontextprotocol.io/docs/tools/inspector

1. Inicie el servidor de desarrollo:

   pnpm watch # Keep this running in one terminal

2. En una terminal separada, inicie el inspector:

   pnpm inspector

3. Configurar el entorno:

   • Agregue su CIRCLECI_TOKEN a la sección Variables de entorno en la interfaz de usuario del inspector

   • El token necesita acceso de lectura a sus proyectos CircleCI

   • Opcionalmente, puede configurar la URL base de CircleCI. El valor predeterminado es https//circleci.com

Pruebas

• Ejecute el conjunto de pruebas:

  pnpm test

• Ejecutar pruebas en modo de observación durante el desarrollo:

  pnpm test:watch

Para obtener pautas de contribución más detalladas, consulte CONTRIBUTING.md