CircleCI

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-premise. 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 a .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 depois armazenadas com segurança pelo VS Code.

Usando Docker em um Servidor MCP local

Adicione o seguinte a .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 em .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 aponte seu claude_desktop_config.json para ele.

Para encontrar ou criar seu arquivo de configuração, abra as configurações do Claude Desktop, clique em Developer na barra lateral esquerda e depois 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 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 adicione-o via a 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. Digite um nome (ex.: circleci-remote-mcp)
5. Selecione o protocolo de transporte: stdio
6. Digite o caminho do comando para o 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

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

• Valida seu .circleci/config.yml quanto a 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"

Baixa dados de uso da API de Uso do CircleCI para uma organização específica. Aceita entrada de data flexível (ex.: "março de 2025" ou "mês passado"). Recurso exclusivo da 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 CircleCI analisando o histórico de execução de testes. Utiliza o recurso de detecção de testes instáveis do CircleCI.

Esta ferramenta pode ser usada de três maneiras:

1. Usando Project Slug (Recomendado):

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

2. Usando a URL do Projeto 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 do git remote
   • 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 (exige a env var 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 limite especificado (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 de falha detalhados 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 depois:
   • Exemplo: "Obtenha falhas de build para meu-projeto na branch main"

2. Usando URLs do CircleCI:

   • Forneça diretamente uma URL de job com falha ou de pipeline
   • 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, a URL do git remote e o 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 de execução passo a passo
• Mensagens de falha e contexto

Recupera metadados de testes para jobs do CircleCI, permitindo analisar resultados de testes sem sair da sua IDE. Esta ferramenta pode ser usada de três maneiras:

1. Usando Project Slug e Branch (Recomendado):

   • Exemplo: "Obtenha resultados de testes 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, a URL do git remote e o 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 de execução
• Filtro por resultado de teste

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

1. Usando Project Slug e Branch (Recomendado):

   • Exemplo: "Obtenha o status do pipeline mais recente para my-project no branch main"

2. Usando URL do Projeto CircleCI:

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

3. Usando Contexto do Projeto Local:

   • Funciona a partir do seu workspace local, fornecendo a raiz do workspace, URL remota do git e nome do 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, depois:
   • Exemplo: "Liste artefatos para my-project no 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 Contexto do Projeto Local:

   • Funciona a partir do seu workspace local, fornecendo a raiz do workspace, URL remota do git e nome do 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 para um componente específico do CircleCI em um ambiente. Inclui status de implantação, informações de commit e carimbos de data/hora.

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.

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

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

Dispara 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 my-project no 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 Contexto do Projeto Local:

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

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

Dispara um rollback para um projeto do CircleCI. A ferramenta guia você interativamente por:

1. Seleção de Projeto — lista projetos seguidos para você escolher
2. Seleção de Ambiente — lista ambientes disponíveis (seleção automática se houver apenas um)
3. Seleção de Componente — lista componentes disponíveis (seleção automática se houver apenas um)
4. Seleção de Versão — exibe versões disponíveis; você seleciona o alvo para o rollback
5. Detecção de Modo de Rollback — verifica se um pipeline de rollback está configurado
6. Executar Rollback — duas opções:
   • Rollback de Pipeline: dispara 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 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: Garanta 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 que CIRCLECI_BASE_URL é https://circleci.com
• Redes corporativas: Configure as configuraçõ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: Garanta >= 18.0.0 com node --version
• Atualize o Node.js: Considere a LTS mais recente se estiver enfrentando problemas de compatibilidade
• Gerenciador de pacotes: Verifique se 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
• Tente 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.

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

Ainda precisa de ajuda?

1. Verifique Problemas no GitHub 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