CircleCI

Pré-requisitos:

• Token de API Pessoal do CircleCI (saiba mais)
• NPX: Node.js ^22.23.4 || ^24.22.1 || >=26.12.1 e pnpm
• Docker: Docker

Usando NPX em um MCP Server 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 MCP Server 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 Self-Managed Remote MCP Server

Consulte Self-Managed Remote MCP Server. 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 ^22.23.4 || ^24.22.1 || >=26.12.1 e pnpm
• Docker: Docker

Usando NPX em um MCP Server 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 depois armazenadas com segurança pelo VS Code.

Usando Docker em um MCP Server 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 Self-Managed Remote MCP Server

Consulte Self-Managed Remote MCP Server. 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 ^22.23.4 || ^24.22.1 || >=26.12.1 e pnpm
• Docker: Docker

Usando NPX em um MCP Server 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 MCP Server 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 Self-Managed Remote MCP Server

Consulte Self-Managed Remote MCP Server. Crie um script wrapper conforme mostrado em Claude Desktop and CLI clients e então 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 então 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 ^22.23.4 || ^24.22.1 || >=26.12.1 e pnpm
• Docker: Docker

Usando NPX em um MCP Server local

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

Usando Docker em um MCP Server 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 Self-Managed Remote MCP Server

Consulte Self-Managed Remote MCP Server e a configuração do cliente Claude Code lá.

Pré-requisitos:

• Token de API Pessoal do CircleCI (saiba mais)
• NPX: Node.js ^22.23.4 || ^24.22.1 || >=26.12.1 e pnpm
• Docker: Docker

Usando NPX em um MCP Server 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 MCP Server 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 Self-Managed Remote MCP Server

Consulte Self-Managed Remote MCP Server. 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 ^22.23.4 || ^24.22.1 || >=26.12.1 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 do 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 MCP Server 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 Self-Managed Remote MCP Server

Consulte Self-Managed Remote MCP Server. Use um script wrapper conforme mostrado em Claude Desktop and CLI clients e então registre-o com q mcp add.

Pré-requisitos:

• Token de API Pessoal do CircleCI (saiba mais)
• NPX: Node.js ^22.23.4 || ^24.22.1 || >=26.12.1 e pnpm

Usando NPX em um MCP Server 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 Self-Managed Remote MCP Server

Consulte Self-Managed Remote MCP Server. Use um script wrapper conforme mostrado em Claude Desktop and CLI clients e então adicione-o pela 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 o seu script
7. Clique em Save

Para instalar o CircleCI MCP Server no 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 no meu branch e obtenha os logs" — consulte 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ânticos
• Fornece resultados detalhados de validação 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 determinada organização. Aceita entrada de data flexível (ex.: "março de 2025" ou "mês passado"). Recurso exclusivo do Cloud.

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. Aproveita o recurso de detecção de testes instáveis do 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, depois:
   • Exemplo: "Obtenha testes instáveis do my-project"

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 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 os 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 falhas de builds do CircleCI. Esta ferramenta pode ser usada de três maneiras:

1. Usando o Project Slug e o Branch (Recomendado):

   • Primeiro use list_followed_projects para obter seus projetos, depois:
   • Exemplo: "Obtenha falhas de build do my-project no branch main"

2. Usando URLs do CircleCI:

   • Forneça diretamente a URL de um job com falha ou a URL de um 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 remota do git e o nome do branch
   • Exemplo: "Encontre o pipeline com falha mais recente no meu 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 de jobs do CircleCI, permitindo que você analise os resultados dos testes sem sair da sua IDE. Esta ferramenta pode ser usada de três maneiras:

1. Usando o Project Slug e o Branch (Recomendado):

   • Exemplo: "Obtenha os resultados de testes do my-project no branch main"

2. Usando a 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 remota do git e o nome do 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 seus tempos
• Filtro por resultado de teste

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

1. Usando Project Slug e Branch (Recomendado):

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

2. Usando a URL do Projeto no CircleCI:

   • Exemplo: "Obtenha o status do pipeline mais recente de 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, a URL remota do git e o 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 os artefatos do my-project no branch main"

2. Usando a 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, a URL remota do git e o nome do branch

Útil para:

• Encontrar URLs de download de 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, caso não sejam 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 segue no CircleCI.

• Mostra todos os projetos aos quais você tem acesso com seu 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.

Executa novamente um workflow desde o início ou a partir do job que falhou.

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

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

1. Usando Project Slug e Branch (Recomendado):

   • Exemplo: "Execute o pipeline do my-project no branch main"

2. Usando a URL do CircleCI:

   • URL do Pipeline, URL do Workflow, URL do Job ou URL do Projeto com branch
   • Exemplo: "Execute o pipeline 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 remota do git e o 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 orienta você interativamente por meio de:

1. Seleção de Projeto — lista os projetos seguidos para você escolher
2. Seleção de Ambiente — lista os ambientes disponíveis (seleciona automaticamente se houver apenas um)
3. Seleção de Componente — lista os componentes disponíveis (seleciona automaticamente se houver apenas um)
4. Seleção de Versão — exibe as versões disponíveis; você seleciona o destino do 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: dispara o pipeline de rollback
   • Reexecução de Workflow: executa novamente um workflow anterior usando seu workflow ID
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 sua IDE completamente (não apenas recarregue a janela)

• Erros de token inválido: Verifique seu CIRCLECI_TOKEN em Personal API Tokens
• 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 que CIRCLECI_BASE_URL é https://circleci.com
• Redes corporativas: Configure as definições de proxy do npm se estiver atrás de um firewall
• Bloqueio por firewall: Verifique se o software de segurança bloqueia downloads de pacotes

• Versão do Node.js: Certifique-se de que atende a ^22.23.4 || ^24.22.1 || >=26.12.1 com node --version
• Atualizar o Node.js: Considere a versão LTS mais recente se estiver enfrentando 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 sistema operacional
• Erros de sintaxe: Valide a sintaxe JSON no seu arquivo de configuração
• Logs do console: Verifique o console do desenvolvedor da IDE para erros específicos
• Tente uma IDE diferente: Teste em outro editor compatível para isolar o problema

Processos travados — encerre os processos MCP existentes:

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

# Windows:
taskkill /f /im node.exe

Conflitos de porta: Reinicie sua 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
• Alternativa com Docker: Tente a instalação via Docker se o npx falhar consistentemente

Ainda precisa de ajuda?

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