CircleCI

Requisitos previos:

• Token de API Personal de CircleCI (más información)
• NPX: Node.js >= v18 y pnpm
• Docker: Docker

Usando NPX en un Servidor MCP local

Añade lo siguiente a la configuración MCP de tu Cursor:

{
  "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 es opcional, requerido solo para clientes on-premise. MAX_MCP_OUTPUT_LENGTH es opcional: longitud máxima de salida para las respuestas MCP (valor por defecto: 50000).

Usando Docker en un Servidor MCP local

Añade lo siguiente a la configuración MCP de tu Cursor:

{
  "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"
      }
    }
  }
}

Usando un Servidor MCP Remoto Autogestionado

Consulta Servidor MCP Remoto Autogestionado. Usa la configuración de cliente por usuario y añádela a la configuración MCP de tu Cursor (Cursor Settings → MCP).

Requisitos previos:

• Token de API Personal de CircleCI (más información)
• NPX: Node.js >= v18 y pnpm
• Docker: Docker

Usando NPX en un Servidor MCP local

Añade lo siguiente a .vscode/mcp.json en tu proyecto:

{
  "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}"
      }
    }
  }
}

💡 Las entradas se solicitan en el primer inicio del servidor y luego se almacenan de forma segura por VS Code.

Usando Docker en un Servidor MCP local

Añade lo siguiente a .vscode/mcp.json en tu proyecto:

{
  "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}"
      }
    }
  }
}

Usando un Servidor MCP Remoto Autogestionado

Consulta Servidor MCP Remoto Autogestionado. Usa la configuración de cliente por usuario en .vscode/mcp.json.

Requisitos previos:

• Token de API Personal de CircleCI (más información)
• NPX: Node.js >= v18 y pnpm
• Docker: Docker

Usando NPX en un Servidor MCP local

Añade lo siguiente a tu 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"
      }
    }
  }
}

Usando Docker en un Servidor MCP local

Añade lo siguiente a tu 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"
      }
    }
  }
}

Usando un Servidor MCP Remoto Autogestionado

Consulta Servidor MCP Remoto Autogestionado. Crea un script envolvente como se muestra en Clientes de escritorio y CLI de Claude, luego apunta tu claude_desktop_config.json hacia él.

Para encontrar o crear tu archivo de configuración, abre la configuración de Claude Desktop, haz clic en Developer en la barra lateral izquierda, luego haz clic en Edit Config. El archivo de configuración se encuentra en:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Para más información: https://modelcontextprotocol.io/quickstart/user

Requisitos previos:

• Token de API Personal de CircleCI (más información)
• NPX: Node.js >= v18 y pnpm
• Docker: Docker

Usando NPX en un Servidor MCP local

claude mcp add circleci-mcp-server -e CIRCLECI_TOKEN=your-circleci-token -- npx -y @circleci/mcp-server-circleci@latest

Usando Docker en un Servidor 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

Usando un Servidor MCP Remoto Autogestionado

Consulta Servidor MCP Remoto Autogestionado y la configuración del cliente Claude Code allí.

Requisitos previos:

• Token de API Personal de CircleCI (más información)
• NPX: Node.js >= v18 y pnpm
• Docker: Docker

Usando NPX en un Servidor MCP local

Añade lo siguiente a tu mcp_config.json de 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"
      }
    }
  }
}

Usando Docker en un Servidor MCP local

Añade lo siguiente a tu mcp_config.json de 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"
      }
    }
  }
}

Usando un Servidor MCP Remoto Autogestionado

Consulta Servidor MCP Remoto Autogestionado. Usa la configuración de cliente por usuario en tu mcp_config.json de Windsurf.

Para más información: https://docs.windsurf.com/windsurf/mcp

Requisitos previos:

• Token de API Personal de CircleCI (más información)
• NPX: Node.js >= v18 y pnpm

La configuración del cliente MCP en Amazon Q Developer se almacena en formato JSON en un archivo llamado mcp.json. Se admiten dos niveles de configuración:

• Global: ~/.aws/amazonq/mcp.json — se aplica a todos los espacios de trabajo
• Espacio de trabajo: .amazonq/mcp.json — específico para el espacio de trabajo actual

Si ambos archivos existen, sus contenidos se fusionan. En caso de conflicto, la configuración del espacio de trabajo tiene prioridad.

Usando NPX en un Servidor MCP local

Edita ~/.aws/amazonq/mcp.json o crea .amazonq/mcp.json con lo siguiente:

{
  "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
    }
  }
}

Usando un Servidor MCP Remoto Autogestionado

Consulta Servidor MCP Remoto Autogestionado. Usa un script envolvente como se muestra en Clientes de escritorio y CLI de Claude, luego regístralo con q mcp add.

Requisitos previos:

• Token de API Personal de CircleCI (más información)
• NPX: Node.js >= v18 y pnpm

Usando NPX en un Servidor MCP local

Edita ~/.aws/amazonq/mcp.json o crea .amazonq/mcp.json con lo siguiente:

{
  "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
    }
  }
}

Usando un Servidor MCP Remoto Autogestionado

Consulta Servidor MCP Remoto Autogestionado. Usa un script envolvente como se muestra en Clientes de escritorio y CLI de Claude, luego agrégalo a través de la interfaz de usuario de configuración MCP:

1. Accede a la interfaz de usuario de configuración MCP
2. Elige el símbolo +
3. Selecciona el alcance: global o local
4. Introduce un nombre (ej. circleci-remote-mcp)
5. Selecciona el protocolo de transporte: stdio
6. Introduce la ruta del comando para tu script
7. Haz clic en Save

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

npx -y @smithery/cli install @CircleCI-Public/mcp-server-circleci --client claude

Ejemplo: "Encuentra el último pipeline fallido en mi rama y obtén los registros" — consulta la wiki para más ejemplos.

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

Ayuda con las tareas de configuración de CircleCI proporcionando orientación y validación.

• Valida tu .circleci/config.yml en busca de errores de sintaxis y semánticos
• Proporciona resultados de validación detallados y recomendaciones de configuración
• Ejemplo: "Valida mi config de CircleCI"

Descarga datos de uso de la API de uso de CircleCI para una organización determinada. Acepta entrada de fechas flexible (p. ej., "marzo de 2025" o "el mes pasado"). Función solo para cloud.

Opción 1: Inicia un nuevo trabajo de exportación proporcionando:

• orgId, startDate, endDate (máx. 32 días), outputDir

Opción 2: Comprueba/descarga un trabajo de exportación existente proporcionando:

• orgId, jobId, outputDir

Devuelve un archivo CSV con los datos de uso de CircleCI para el período de tiempo especificado.

[!NOTE] Los datos de uso se pueden introducir en la herramienta find_underused_resource_classes para el análisis de optimización de costes.

Identifica tests inestables (flaky) en tu proyecto de CircleCI analizando el historial de ejecución de tests. Aprovecha la función de detección de tests inestables de CircleCI.

Esta herramienta se puede usar de tres maneras:

1. Usando el slug del proyecto (recomendado):

   • Usa primero list_followed_projects para obtener tus proyectos y luego:
   • Ejemplo: "Obtén los tests inestables de mi-proyecto"

2. Usando la URL del proyecto de CircleCI:

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

3. Usando el contexto del proyecto local:

   • Funciona desde tu espacio de trabajo local proporcionando la raíz del espacio de trabajo y la URL remota de git
   • Ejemplo: "Encuentra tests inestables en mi proyecto actual"

Modos de salida:

• Texto (predeterminado): Devuelve los detalles de los tests inestables en formato de texto
• Archivo (requiere la variable de entorno FILE_OUTPUT_DIRECTORY): Crea un directorio con los detalles de los tests inestables

Analiza un archivo CSV de datos de uso de CircleCI para encontrar trabajos con uso medio o máximo de CPU/RAM por debajo de un umbral determinado (predeterminado: 40%).

Proporciona un archivo CSV obtenido de download_usage_api_data.

Devuelve una lista en markdown de trabajos poco utilizados organizados por proyecto y workflow — útil para identificar oportunidades de optimización de costes.

Recupera registros de error detallados de los builds de CircleCI. Esta herramienta se puede usar de tres maneras:

1. Usando el slug del proyecto y la rama (recomendado):

   • Usa primero list_followed_projects para obtener tus proyectos y luego:
   • Ejemplo: "Obtén los errores de build de mi-proyecto en la rama main"

2. Usando URLs de CircleCI:

   • Proporciona directamente la URL de un trabajo fallido o la URL de un pipeline
   • Ejemplo: "Obtén los registros de https://app.circleci.com/pipelines/github/org/repo/123"

3. Usando el contexto del proyecto local:

   • Funciona desde tu espacio de trabajo local proporcionando la raíz del espacio de trabajo, la URL remota de git y el nombre de la rama
   • Ejemplo: "Encuentra el último pipeline fallido en mi rama actual"

La herramienta devuelve registros formateados que incluyen:

• Nombres de los trabajos
• Detalles de ejecución paso a paso
• Mensajes de error y contexto

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

1. Usando el slug del proyecto y la rama (recomendado):

   • Ejemplo: "Obtén los resultados de los tests de mi-proyecto en la rama main"

2. Usando la URL de CircleCI:

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

3. Usando el contexto del proyecto local:

   • Funciona desde tu espacio de trabajo local proporcionando la raíz del espacio de trabajo, la URL remota de git y el nombre de la rama

La herramienta devuelve:

• Resumen de todos los tests (total, correctos, fallidos)
• Información detallada de los tests fallidos: nombre, clase, archivo, mensaje de error, duración
• Lista de tests correctos con tiempos
• Filtro por resultado del test

[!NOTE] Los metadatos de tests deben configurarse en tu archivo de configuración de CircleCI. Consulta Collect Test Data para obtener instrucciones de configuración.

1. Usando Project Slug y rama (recomendado):

   • Ejemplo: "Obtén el estado de la última pipeline de mi-proyecto en la rama main"

2. Usando la URL del proyecto de CircleCI:

   • Ejemplo: "Obtén el estado de la última pipeline para https://app.circleci.com/pipelines/github/org/repo"

3. Usando el contexto del proyecto local:

   • Funciona desde tu espacio de trabajo local proporcionando la raíz del workspace, la URL remota de git y el nombre de la rama

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

Recupera la lista de artefactos producidos por un job de CircleCI. Esta herramienta puede utilizarse de tres formas:

1. Usando Project Slug y rama (recomendado):

   • Primero usa list_followed_projects para obtener tus proyectos, luego:
   • Ejemplo: "Lista los artefactos de mi-proyecto en la rama main"

2. Usando la URL de CircleCI:

   • URL del job: https://app.circleci.com/pipelines/gh/organization/project/123/workflows/abc-def/jobs/789
   • URL del workflow: https://app.circleci.com/pipelines/gh/organization/project/123/workflows/abc-def
   • URL de la pipeline: https://app.circleci.com/pipelines/gh/organization/project/123

3. Usando el contexto del proyecto local:

   • Funciona desde tu espacio de trabajo local proporcionando la raíz del workspace, la URL remota de git y el nombre de la rama

Útil para:

• Encontrar URL de descarga de artefactos de compilación (binarios, informes, registros)
• Verificar qué artefactos se produjeron en una ejecución de pipeline

Lista todas las versiones de un componente específico de CircleCI en un entorno. Incluye estado de despliegue, información del commit y marcas de tiempo.

La herramienta te pedirá que selecciones el componente y el entorno si no se proporcionan.

Útil para:

• Identificar qué versión está actualmente en producción
• Seleccionar versiones objetivo para operaciones de rollback
• Obtener detalles del despliegue (pipeline, workflow, job)

Lista todos los proyectos que el usuario sigue en CircleCI.

• Muestra todos los proyectos a los que tienes acceso con su projectSlug
• Ejemplo: "Lista mis proyectos de CircleCI"

Ejemplo de salida:

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

[!NOTE] El projectSlug (no el nombre del proyecto) es obligatorio para muchas otras herramientas de CircleCI.

Vuelve a ejecutar un workflow desde su inicio o desde el job que falló.

Devuelve el ID del workflow recién creado y un enlace para monitorearlo.

Dispara la ejecución de una pipeline. Esta herramienta puede utilizarse de tres formas:

1. Usando Project Slug y rama (recomendado):

   • Ejemplo: "Ejecuta la pipeline de mi-proyecto en la rama main"

2. Usando la URL de CircleCI:

   • URL de la pipeline, URL del workflow, URL del job o URL del proyecto con rama
   • Ejemplo: "Ejecuta la pipeline para https://app.circleci.com/pipelines/github/org/repo/123"

3. Usando el contexto del proyecto local:

   • Funciona desde tu espacio de trabajo local proporcionando la raíz del workspace, la URL remota de git y el nombre de la rama

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

Dispara un rollback para un proyecto de CircleCI. La herramienta te guía de forma interactiva a través de:

1. Selección de proyecto — lista los proyectos seguidos para que elijas
2. Selección de entorno — lista los entornos disponibles (se selecciona automáticamente si solo hay uno)
3. Selección de componente — lista los componentes disponibles (se selecciona automáticamente si solo hay uno)
4. Selección de versión — muestra las versiones disponibles; seleccionas el objetivo del rollback
5. Detección del modo de rollback — verifica si hay una pipeline de rollback configurada
6. Ejecutar el rollback — dos opciones:
   • Rollback de pipeline: dispara la pipeline de rollback
   • Reejecución de workflow: vuelve a ejecutar un workflow anterior usando su ID de workflow
7. Confirmación — resume y confirma antes de la ejecución

Los problemas más comunes:

1. Limpia las cachés de paquetes:

   npx clear-npx-cache
   npm cache clean --force
   

2. Forzar la versión más reciente: Agrega @latest a tu configuración:

   "args": ["-y", "@circleci/mcp-server-circleci@latest"]
   

3. Reinicia tu IDE por completo (no solo recargues la ventana)

• Errores de token no válido: Verifica tu CIRCLECI_TOKEN en Personal API Tokens
• Errores de permisos: Asegúrate de que el token tenga acceso de lectura a tus proyectos
• Variables de entorno que no se cargan: Prueba con echo $CIRCLECI_TOKEN (Mac/Linux) o echo %CIRCLECI_TOKEN% (Windows)

• URL base: Confirma que CIRCLECI_BASE_URL sea https://circleci.com
• Redes corporativas: Configura el proxy de npm si estás detrás de un firewall
• Bloqueo por firewall: Verifica si el software de seguridad bloquea las descargas de paquetes

• Versión de Node.js: Asegúrate de tener >= 18.0.0 con node --version
• Actualizar Node.js: Considera la última LTS si tienes problemas de compatibilidad
• Gestor de paquetes: Verifica que npm/pnpm funcione: npm --version

• Ubicación del archivo de configuración: Vuelve a verificar la ruta para tu sistema operativo
• Errores de sintaxis: Valida la sintaxis JSON en tu archivo de configuración
• Registros de consola: Revisa la consola de desarrollador del IDE para ver errores específicos
• Prueba con otro IDE: Prueba en otro editor compatible para aislar el problema

Procesos bloqueados: mata los procesos MCP existentes:

# Mac/Linux:
pkill -f "mcp-server-circleci"

# Windows:
taskkill /f /im node.exe

Conflictos de puerto: Reinicia tu IDE si la conexión parece bloqueada.

• Prueba el paquete directamente: npx @circleci/mcp-server-circleci@latest --help
• Registro detallado (verbose): DEBUG=* npx @circleci/mcp-server-circleci@latest
• Alternativa con Docker: Prueba la instalación mediante Docker si npx falla de forma consistente

¿Aún necesitas ayuda?

1. Revisa GitHub Issues para problemas similares
2. Incluye tu sistema operativo, versión de Node e IDE al informar problemas
3. Comparte los mensajes de error relevantes de la consola del IDE