CircleCI MCP Server

Pré-requisitos:

• Token de API Pessoal do CircleCI (saiba mais)
• NPX: Node.js >= v18 e pnpm
• Docker: Docker

Usando NPX em um Servidor MCP local

Adicione o seguinte à sua configuração MCP do 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 é opcional — necessário apenas para clientes on-prem. MAX_MCP_OUTPUT_LENGTH é opcional — comprimento máximo de saída para respostas MCP (padrão: 50000).

Usando Docker em um Servidor MCP local

Adicione o seguinte à sua configuração MCP do 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 um Servidor MCP Remoto Autogerenciado

Consulte Servidor MCP Remoto Autogerenciado. Use a configuração de cliente por usuário e adicione-a à sua configuração MCP do Cursor (Cursor Settings → MCP).

Pré-requisitos:

• Token de API Pessoal do CircleCI (saiba mais)
• NPX: Node.js >= v18 e pnpm
• Docker: Docker

Usando NPX em um Servidor MCP local

Adicione o seguinte ao .vscode/mcp.json no seu projeto:

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

💡 As entradas são solicitadas na primeira inicialização do servidor e, em seguida, armazenadas com segurança pelo VS Code.

Usando Docker em um Servidor MCP local

Adicione o seguinte ao .vscode/mcp.json no seu projeto:

{
  "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 um Servidor MCP Remoto Autogerenciado

Consulte Servidor MCP Remoto Autogerenciado. Use a configuração de cliente por usuário no .vscode/mcp.json.

Pré-requisitos:

• Token de API Pessoal do CircleCI (saiba mais)
• NPX: Node.js >= v18 e pnpm
• Docker: Docker

Usando NPX em um Servidor MCP local

Adicione o seguinte ao seu 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 em um Servidor MCP local

Adicione o seguinte ao seu 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 um Servidor MCP Remoto Autogerenciado

Consulte Servidor MCP Remoto Autogerenciado. Crie um script wrapper conforme mostrado em Clientes Claude Desktop e CLI e, em seguida, aponte seu claude_desktop_config.json para ele.

Para localizar ou criar seu arquivo de configuração, abra as configurações do Claude Desktop, clique em Developer na barra lateral esquerda e, em seguida, clique em Edit Config. O arquivo de configuração está localizado em:

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

Para mais informações: https://modelcontextprotocol.io/quickstart/user

Pré-requisitos:

• Token de API Pessoal do CircleCI (saiba mais)
• NPX: Node.js >= v18 e pnpm
• Docker: Docker

Usando NPX em um Servidor MCP local

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

Usando Docker em um 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 um Servidor MCP Remoto Autogerenciado

Consulte Servidor MCP Remoto Autogerenciado e a configuração do cliente Claude Code lá.

Pré-requisitos:

• Token de API Pessoal do CircleCI (saiba mais)
• NPX: Node.js >= v18 e pnpm
• Docker: Docker

Usando NPX em um Servidor MCP local

Adicione o seguinte ao seu mcp_config.json do 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 em um Servidor MCP local

Adicione o seguinte ao seu mcp_config.json do 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 um Servidor MCP Remoto Autogerenciado

Consulte Servidor MCP Remoto Autogerenciado. Use a configuração de cliente por usuário no seu mcp_config.json do Windsurf.

Para mais informações: https://docs.windsurf.com/windsurf/mcp

Pré-requisitos:

• Token de API Pessoal do CircleCI (saiba mais)
• NPX: Node.js >= v18 e pnpm

A configuração do cliente MCP no Amazon Q Developer é armazenada em formato JSON em um arquivo chamado mcp.json. Dois níveis de configuração são suportados:

• Global: ~/.aws/amazonq/mcp.json — aplica-se a todos os workspaces
• Workspace: .amazonq/mcp.json — específico para o workspace atual

Se ambos os arquivos existirem, seus conteúdos são mesclados. Em caso de conflito, a configuração do workspace tem precedência.

Usando NPX em um Servidor MCP local

Edite ~/.aws/amazonq/mcp.json ou crie .amazonq/mcp.json com o seguinte:

{
  "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 um Servidor MCP Remoto Autogerenciado

Consulte Servidor MCP Remoto Autogerenciado. Use um script wrapper conforme mostrado em Clientes Claude Desktop e CLI e, em seguida, registre-o com q mcp add.

Pré-requisitos:

• Token de API Pessoal do CircleCI (saiba mais)
• NPX: Node.js >= v18 e pnpm

Usando NPX em um Servidor MCP local

Edite ~/.aws/amazonq/mcp.json ou crie .amazonq/mcp.json com o seguinte:

{
  "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 um Servidor MCP Remoto Autogerenciado

Consulte Servidor MCP Remoto Autogerenciado. Use um script wrapper conforme mostrado em Clientes Claude Desktop e CLI e, em seguida, adicione-o através da interface de configuração MCP:

1. Acesse a interface de configuração MCP
2. Escolha o símbolo +
3. Selecione o escopo: global ou local
4. Insira um nome (ex.: circleci-remote-mcp)
5. Selecione o protocolo de transporte: stdio
6. Insira o caminho do comando para seu script
7. Clique em Save

Para instalar o Servidor MCP do CircleCI para Claude Desktop automaticamente via Smithery:

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

Exemplo: "Encontre o pipeline com falha mais recente na minha branch e obtenha os logs" — veja a wiki para mais exemplos.

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

Analisa diffs do git em relação às regras do cursor para identificar violações de regras.

Forneça:

• Conteúdo do git diff (ex.: git diff --cached, git diff HEAD)
• Regras do repositório de .cursorrules ou .cursor/rules

Retorna relatórios detalhados de violação com pontuações de confiança e explicações.

Útil para:

• Verificações de qualidade de código pré-commit
• Garantir consistência com os padrões de codificação da equipe
• Capturar violações de regras antes da revisão de código

Auxilia nas tarefas de configuração do CircleCI, fornecendo orientação e validação.

• Valida seu .circleci/config.yml em busca de erros de sintaxe e semântica
• Fornece resultados de validação detalhados e recomendações de configuração
• Exemplo: "Valide minha configuração do CircleCI"

Gera modelos de prompt estruturados para aplicações habilitadas para IA com base nos requisitos do recurso.

• Transforma os requisitos do usuário em modelos de prompt otimizados
• Retorna um modelo estruturado e um esquema de contexto definindo os parâmetros de entrada necessários
• Exemplo: "Crie um modelo de prompt para gerar histórias de ninar por idade e tópico"

Baixa dados de uso da API de Uso do CircleCI para uma determinada organização. Aceita entrada de data flexível (ex.: "Março de 2025" ou "mês passado"). Recurso apenas para nuvem.

Opção 1: Inicie um novo job de exportação fornecendo:

• orgId, startDate, endDate (máx. 32 dias), outputDir

Opção 2: Verifique/baixe um job de exportação existente fornecendo:

• orgId, jobId, outputDir

Retorna um arquivo CSV com dados de uso do CircleCI para o período especificado.

[!NOTE] Os dados de uso podem ser alimentados na ferramenta find_underused_resource_classes para análise de otimização de custos.

Identifica testes instáveis no seu projeto do CircleCI analisando o histórico de execução de testes. Aproveita o recurso de detecção de testes instáveis no CircleCI.

Esta ferramenta pode ser usada de três maneiras:

1. Usando o Project Slug (Recomendado):

   • Primeiro use list_followed_projects para obter seus projetos e, em seguida:
   • Exemplo: "Obtenha testes instáveis para meu-projeto"

2. Usando a URL do Projeto no CircleCI:

   • Exemplo: "Encontre testes instáveis em https://app.circleci.com/pipelines/github/org/repo"

3. Usando o Contexto do Projeto Local:

   • Funciona a partir do seu workspace local, fornecendo a raiz do workspace e a URL remota do git
   • Exemplo: "Encontre testes instáveis no meu projeto atual"

Modos de saída:

• Texto (padrão): Retorna detalhes dos testes instáveis em formato de texto
• Arquivo (requer a variável de ambiente FILE_OUTPUT_DIRECTORY): Cria um diretório com detalhes dos testes instáveis

Analisa um arquivo CSV de dados de uso do CircleCI para encontrar jobs com uso médio ou máximo de CPU/RAM abaixo de um determinado limite (padrão: 40%).

Forneça um arquivo CSV obtido de download_usage_api_data.

Retorna uma lista em markdown de jobs subutilizados organizados por projeto e workflow — útil para identificar oportunidades de otimização de custos.

Recupera logs detalhados de falha de builds do CircleCI. Esta ferramenta pode ser usada de três maneiras:

1. Usando Project Slug e Branch (Recomendado):

   • Primeiro use list_followed_projects para obter seus projetos e, em seguida:
   • Exemplo: "Obtenha falhas de build para meu-projeto na branch main"

2. Usando URLs do CircleCI:

   • Forneça uma URL de job com falha ou URL de pipeline diretamente
   • Exemplo: "Obtenha logs de https://app.circleci.com/pipelines/github/org/repo/123"

3. Usando o Contexto do Projeto Local:

   • Funciona a partir do seu workspace local, fornecendo a raiz do workspace, URL remota do git e nome da branch
   • Exemplo: "Encontre o pipeline com falha mais recente na minha branch atual"

A ferramenta retorna logs formatados incluindo:

• Nomes dos jobs
• Detalhes da execução passo a passo
• Mensagens de falha e contexto

Recupera metadados de teste para jobs do CircleCI, permitindo que você analise os resultados dos testes sem sair do seu IDE. Esta ferramenta pode ser usada de três maneiras:

1. Usando Project Slug e Branch (Recomendado):

   • Exemplo: "Obtenha resultados de teste para meu-projeto na branch main"

2. Usando URL do CircleCI:

   • URL do Job: https://app.circleci.com/pipelines/github/org/repo/123/workflows/abc-def/jobs/789
   • URL do Workflow: https://app.circleci.com/pipelines/github/org/repo/123/workflows/abc-def
   • URL do Pipeline: https://app.circleci.com/pipelines/github/org/repo/123

3. Usando o Contexto do Projeto Local:

   • Funciona a partir do seu workspace local, fornecendo a raiz do workspace, URL remota do git e nome da branch

A ferramenta retorna:

• Resumo de todos os testes (total, bem-sucedidos, com falha)
• Informações detalhadas sobre testes com falha: nome, classe, arquivo, mensagem de erro, duração
• Lista de testes bem-sucedidos com tempo
• Filtrar por resultado do teste

[!NOTE] Os metadados de teste devem ser configurados na sua configuração do CircleCI. Consulte Coletar Dados de Teste para instruções de configuração.

Recupera o status do pipeline mais recente para uma determinada branch. Esta ferramenta pode ser usada de três maneiras:

1. Usando Project Slug e Branch (Recomendado):

   • Exemplo: "Obtenha o status do pipeline mais recente para meu-projeto na branch main"

2. Usando a URL do Projeto no CircleCI:

   • Exemplo: "Obtenha o status do pipeline mais recente para https://app.circleci.com/pipelines/github/org/repo"

3. Usando o Contexto do Projeto Local:

   • Funciona a partir do seu workspace local, fornecendo a raiz do workspace, URL remota do git e nome da branch

Exemplo de saída:

---
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 a lista de artefatos produzidos por um job do CircleCI. Esta ferramenta pode ser usada de três maneiras:

1. Usando Project Slug e Branch (Recomendado):

   • Primeiro use list_followed_projects para obter seus projetos e, em seguida:
   • Exemplo: "Liste artefatos para meu-projeto na branch main"

2. Usando URL do CircleCI:

   • URL do Job: https://app.circleci.com/pipelines/gh/organization/project/123/workflows/abc-def/jobs/789
   • URL do Workflow: https://app.circleci.com/pipelines/gh/organization/project/123/workflows/abc-def
   • URL do Pipeline: https://app.circleci.com/pipelines/gh/organization/project/123

3. Usando o Contexto do Projeto Local:

   • Funciona a partir do seu workspace local, fornecendo a raiz do workspace, URL remota do git e nome da branch

Útil para:

• Encontrar URLs de download para artefatos de build (binários, relatórios, logs)
• Verificar quais artefatos foram produzidos por uma execução de pipeline

Lista todas as versões de um componente específico do CircleCI em um ambiente. Inclui status de implantação, informações de commit e timestamps.

A ferramenta solicitará que você selecione o componente e o ambiente se não forem fornecidos.

Útil para:

• Identificar qual versão está atualmente em produção
• Selecionar versões de destino para operações de rollback
• Obter detalhes de implantação (pipeline, workflow, job)

Lista todos os projetos que o usuário está seguindo no CircleCI.

• Mostra todos os projetos aos quais você tem acesso com seus projectSlug
• Exemplo: "Liste meus projetos do CircleCI"

Exemplo de saída:

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

[!NOTE] O projectSlug (não o nome do projeto) é necessário para muitas outras ferramentas do CircleCI.

Gera casos de teste para modelos de prompt para garantir que produzam os resultados esperados.

• Cria cenários de teste diversos com base no seu modelo de prompt e esquema de contexto
• Retorna um array de casos de teste recomendados com várias combinações de parâmetros
• Exemplo: "Gere testes para meu modelo de prompt de história de ninar"

Reexecuta um workflow do início ou a partir do job com falha.

Retorna o ID do workflow recém-criado e um link para monitorá-lo.

Executa testes de avaliação (também conhecidos como "Testes de Prompt") em um pipeline do CircleCI. Gera uma configuração apropriada do CircleCI e aciona um pipeline usando-a.

Esta ferramenta pode ser usada de três maneiras:

1. Usando Project Slug e Branch (Recomendado):

   • Primeiro use list_followed_projects para obter seus projetos e, em seguida:
   • Exemplo: "Execute testes de avaliação para meu-projeto na branch main"

2. Usando URL do CircleCI:

   • URL do Projeto, URL do Pipeline, URL do Workflow ou URL do Job
   • Exemplo: "Execute testes de avaliação para https://app.circleci.com/pipelines/gh/organization/project/123"

3. Usando o Contexto do Projeto Local:

   • Funciona a partir do seu workspace local, fornecendo a raiz do workspace, URL remota do git e nome da branch

A ferramenta aceita arquivos de modelo de prompt e retorna uma URL para monitorar o pipeline acionado.

[!NOTE] Se o projeto tiver várias definições de pipeline, a ferramenta retornará uma lista de pipelines disponíveis para você escolher.

Aciona a execução de um pipeline. Esta ferramenta pode ser usada de três maneiras:

1. Usando Project Slug e Branch (Recomendado):

   • Exemplo: "Execute o pipeline para meu-projeto na branch main"

2. Usando URL do CircleCI:

   • URL do Pipeline, URL do Workflow, URL do Job ou URL do Projeto com branch
   • Exemplo: "Execute o pipeline para https://app.circleci.com/pipelines/github/org/repo/123"

3. Usando o Contexto do Projeto Local:

   • Funciona a partir do seu workspace local, fornecendo a raiz do workspace, URL remota do git e nome da branch

A ferramenta retorna um link para monitorar a execução do pipeline.

Aciona um rollback para um projeto do CircleCI. A ferramenta guia você interativamente através de:

1. Seleção do Projeto — lista os projetos seguidos para você escolher
2. Seleção do Ambiente — lista os ambientes disponíveis (seleciona automaticamente se houver apenas um)
3. Seleção do Componente — lista os componentes disponíveis (seleciona automaticamente se houver apenas um)
4. Seleção da Versão — exibe as versões disponíveis; você seleciona o destino para o rollback
5. Detecção do Modo de Rollback — verifica se um pipeline de rollback está configurado
6. Executar Rollback — duas opções:
   • Rollback de Pipeline: aciona o pipeline de rollback
   • Reexecução de Workflow: reexecuta um workflow anterior usando seu ID de workflow
7. Confirmação — resume e confirma antes da execução

Problemas mais comuns:

1. Limpar caches de pacotes:

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

2. Forçar a versão mais recente: Adicione @latest à sua configuração:

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

3. Reinicie seu IDE completamente (não apenas recarregue a janela)

• Erros de token inválido: Verifique seu CIRCLECI_TOKEN em Tokens de API Pessoais
• Erros de permissão: Certifique-se de que o token tenha acesso de leitura aos seus projetos
• Variáveis de ambiente não carregando: Teste com echo $CIRCLECI_TOKEN (Mac/Linux) ou echo %CIRCLECI_TOKEN% (Windows)

• URL Base: Confirme se CIRCLECI_BASE_URL é https://circleci.com
• Redes corporativas: Configure as definições de proxy do npm se estiver atrás de um firewall
• Bloqueio de firewall: Verifique se o software de segurança bloqueia downloads de pacotes

• Versão do Node.js: Certifique-se de que seja >= 18.0.0 com node --version
• Atualizar Node.js: Considere a LTS mais recente se tiver problemas de compatibilidade
• Gerenciador de pacotes: Verifique se o npm/pnpm está funcionando: npm --version

• Localização do arquivo de configuração: Verifique novamente o caminho para o seu SO
• Erros de sintaxe: Valide a sintaxe JSON no seu arquivo de configuração
• Logs do console: Verifique o console do desenvolvedor do IDE para erros específicos
• Experimente um IDE diferente: Teste em outro editor suportado para isolar o problema

Processos travados — mate os processos MCP existentes:

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

# Windows:
taskkill /f /im node.exe

Conflitos de porta: Reinicie seu IDE se a conexão parecer bloqueada.

• Testar o pacote diretamente: npx @circleci/mcp-server-circleci@latest --help
• Log detalhado: DEBUG=* npx @circleci/mcp-server-circleci@latest
• Fallback do Docker: Experimente a instalação do Docker se o npx falhar consistentemente

Ainda precisa de ajuda?

1. Verifique GitHub Issues para problemas semelhantes
2. Inclua seu SO, versão do Node e IDE ao relatar problemas
3. Compartilhe mensagens de erro relevantes do console do IDE