Você pede pro Claude Code mudar um componente, ele edita o arquivo, roda o build sem erro — e mesmo assim você não sabe se a mudança ficou boa na tela até abrir o navegador manualmente, dar refresh e conferir com os próprios olhos. O chrome-devtools-mcp, servidor MCP oficial da equipe do Chrome DevTools, resolve exatamente essa lacuna: conecta o Claude Code a uma instância real do Chrome, então o agente consegue navegar, clicar, tirar screenshot, ler o console e até gravar uma trace de performance sem sair do terminal.

O que esse MCP resolve, de verdade

MCP (Model Context Protocol) é o padrão que dá a um assistente como o Claude Code acesso a ferramentas externas. O chrome-devtools-mcp é um servidor MCP específico: ele expõe o Chrome DevTools Protocol como um conjunto de ferramentas que o agente pode chamar — navegar pra uma URL, preencher formulário, clicar em elemento, tirar screenshot, ler mensagens de console, listar requisições de rede, gravar uma trace de performance, tirar heap snapshot de memória, entre outras.

Na prática, isso fecha o ciclo que hoje é manual: você descreve o que quer, o agente edita o código, e o próprio agente confere o resultado no navegador — sem você precisar copiar screenshot, colar erro de console ou descrever "a régua desalinhou" de novo. Se você já tem familiaridade com o conceito geral de MCP, isso é só mais um servidor pra registrar no seu cliente; se não tem, vale ler primeiro o artigo sobre o que é o Model Context Protocol antes de seguir.

O projeto é mantido pela própria organização ChromeDevTools no GitHub (não é fork de terceiro — vale o cuidado, porque existem forks parecidos circulando com nome quase idêntico que não são oficiais). Licença Apache-2.0, repositório com quase 50 mil estrelas e lançamentos frequentes, várias vezes por mês, desde o anúncio oficial em 23 de setembro de 2025 (preview público) — a versão mais recente confirmada nesta apuração é a v1.7.0, de 10 de agosto de 2026, então não é projeto abandonado.

Pra quem é isso

  • Quem já usa Claude Code pra escrever/editar frontend (React, Vue, HTML puro, o que for) e quer que o agente confira visualmente o resultado, não só compile.
  • Quem quer diagnosticar performance de página (Core Web Vitals — LCP, INP, CLS) sem abrir o DevTools manualmente e interpretar a trace sozinho.
  • Quem quer automatizar debugging repetitivo — reproduzir um bug clicando nos mesmos passos, ler o console, checar requisição de rede que falhou.

Este texto não assume que você já usou MCP ou Chrome DevTools Protocol antes — só que já roda um projeto frontend localmente e já usa o Claude Code no terminal.

Requisitos

  • Node.js em versão LTS.
  • npm disponível (vem junto com o Node.js).
  • Google Chrome atualizado (versão estável atual ou mais nova) ou Chrome for Testing — são os dois únicos navegadores oficialmente suportados. Outros navegadores baseados em Chromium podem funcionar, mas sem garantia.
  • Claude Code instalado e funcionando no terminal.
O ambiente onde este artigo foi escrito não tem Chrome instalado (é um ambiente headless/CI, sem navegador gráfico) — então os dois cenários de uso completos deste tutorial não puderam ser executados ponta a ponta aqui. O que foi testado de verdade, e onde, está marcado explicitamente em cada seção abaixo.

Como instalar e configurar no Claude Code

Existem duas formas equivalentes. A mais simples é o comando de CLI que o próprio README do projeto documenta especificamente pra Claude Code:

# Adiciona o servidor no escopo "user" (fica disponível em
# todos os seus projetos, só pra você — não versiona com o time)
claude mcp add chrome-devtools --scope user -- npx -y chrome-devtools-mcp@latest

Se preferir compartilhar a configuração com o time (versionada no repositório), use escopo project — aí o Claude Code cria/edita um arquivo .mcp.json na raiz do projeto:

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@latest"]
    }
  }
}

Repare que essa é literalmente a configuração recomendada pelo README oficial pra "qualquer cliente MCP" — o Claude Code lê esse mesmo formato dentro de mcpServers. Cada colega que clonar o repositório precisa aprovar o servidor na primeira vez que abrir o Claude Code no projeto (é uma proteção contra servidor MCP malicioso injetado num repositório — nunca aprove um servidor que você não configurou você mesmo).

Não é preciso instalar o pacote antes — o npx -y chrome-devtools-mcp@latest baixa (ou reaproveita do cache) e roda a versão mais recente automaticamente toda vez que o Claude Code inicia o servidor.

O que testamos neste ambiente

TESTADO NESTE AMBIENTE: rodamos npx -y chrome-devtools-mcp@latest --help e npx -y chrome-devtools-mcp@latest --version neste ambiente (Node.js v24.14.1). O pacote instalou e respondeu corretamente, confirmando a versão 1.7.0 — bate com a última release oficial pesquisada. O --help também confirmou, direto da CLI real (não só da documentação), a existência das flags --no-usage-statistics, --no-performance-crux, --isolated e --slim citadas mais abaixo.

NÃO EXECUTADO NESTE AMBIENTE: o comando claude mcp add em si, a conexão de fato com um Chrome rodando, e os dois cenários de uso da seção seguinte — porque este ambiente não tem Chrome instalado nem sessão de Claude Code interativa disponível pra testar a integração ponta a ponta. Os comandos abaixo vêm do README oficial do projeto e da documentação oficial do Claude Code, conferidos linha a linha, mas não foram rodados antes de publicar.

Como verificar que a conexão funcionou

Depois de adicionar o servidor (por qualquer uma das duas formas acima), confirme:

  1. Rode claude mcp list no terminal — chrome-devtools deve aparecer com status ✔ Connected. Se aparecer ✘ Failed to connect, o comando também mostra o erro (procure algo relacionado a "Chrome não encontrado" — nesse caso confirme o requisito de Chrome instalado acima).
  2. Ou, dentro de uma sessão já aberta do Claude Code, digite /mcp — o painel lista os servidores conectados e quantas ferramentas cada um expõe.
  3. Mande o prompt de teste que o próprio README sugere:
Check the performance of https://developers.chrome.com

Se a conexão estiver funcionando, o Claude Code deve abrir uma janela do Chrome sozinho (o navegador só abre quando alguma ferramenta que precisa dele é chamada — conectar ao servidor MCP, isoladamente, não abre nada) e voltar com um resumo da trace de performance daquela página.

Cenário 1: pedir pro Claude Code alterar um componente e conferir visualmente

Com o projeto frontend rodando localmente (ex. npm run dev numa porta como 3000) e o chrome-devtools-mcp conectado, o fluxo natural é pedir a mudança e a verificação na mesma instrução — o agente decide sozinho quais ferramentas usar (navigate_page pra abrir a página, take_screenshot pra registrar o resultado, list_console_messages se algo quebrar):

Aumenta o padding do card de preço em components/PricingCard.tsx
pra 24px, abre http://localhost:3000/precos no Chrome e tira um
screenshot pra eu ver como ficou. Se aparecer algum erro no console,
me mostra.

O ganho real aqui não é só "o agente vê a tela" — é que ele consegue iterar sozinho: editar, recarregar, olhar o resultado, perceber que ficou ruim (ex. o card estourou o container) e corrigir de novo, sem você precisar ficar de intermediário entre editor e navegador em cada rodada.

Cenário 2: rodar uma análise de performance real com performance_start_trace

A ferramenta performance_start_trace grava uma trace de performance da página selecionada — útil pra achar gargalo de Core Web Vitals (LCP, INP, CLS) sem abrir a aba Performance do DevTools manualmente e ler o flame chart você mesmo. Ela aceita três parâmetros opcionais, conforme a referência oficial de ferramentas: reload (recarrega a página assim que a gravação começa), autoStop (encerra a gravação automaticamente) e filePath (salva a trace bruta em disco). O próprio guia recomenda navegar pra URL certa antes de iniciar a trace quando for usar reload ou autoStop.

Abre http://localhost:3000 no Chrome, grava uma performance trace
recarregando a página do zero, e me diz se o LCP está bom e qual
elemento está causando o maior atraso.

Por trás disso, o agente normalmente encadeia navigate_page → performance_start_trace (com reload: true) → performance_stop_trace → performance_analyze_insight pra detalhar um insight específico (ex. "LCPBreakdown") sem que você precise saber o nome dessas ferramentas de antemão — só descreva o que quer saber sobre a performance da página.

Segurança e telemetria — o que você está expondo

Vale ler antes de sair usando em qualquer projeto:

  • O Chrome controlado pelo MCP é um navegador real. Qualquer cliente MCP conectado (o Claude Code, no seu caso) consegue inspecionar, ler e modificar o que estiver aberto nesse navegador — inclusive sessão logada, se você usar um perfil com login ativo. O próprio README avisa: evite expor informação sensível ou pessoal que você não queira compartilhar com o cliente MCP.
  • Por padrão já é um perfil dedicado, não o seu perfil pessoal. O chrome-devtools-mcp abre uma instância nova do Chrome usando um diretório de dados próprio ($HOME/.cache/chrome-devtools-mcp/chrome-profile no Linux/macOS, %USERPROFILE%\.cache\chrome-devtools-mcp\chrome-profile no Windows) — separado do seu Chrome do dia a dia. Isso já reduz bastante o risco, mas esse perfil dedicado persiste entre execuções (não é limpo sozinho); se você não quiser reaproveitar cookies/histórico entre sessões, adicione a flag --isolated, que cria um perfil temporário apagado automaticamente ao fechar o navegador.
  • Telemetria de uso vem ligada por padrão. O Google coleta estatísticas de uso (taxa de sucesso de chamada de ferramenta, latência, informação de ambiente) pra melhorar a confiabilidade do próprio chrome-devtools-mcp, sob a Política de Privacidade do Google. Pra desligar, adicione a flag --no-usage-statistics aos args da configuração (ou defina a variável de ambiente CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS).
  • Ferramentas de performance enviam URL pra API do Google. As ferramentas de trace podem mandar a URL analisada pra API pública Chrome User Experience Report (CrUX), pra complementar o dado de laboratório com dado de campo real. Desligue com a flag --no-performance-crux se estiver testando URL interna/privada que não deveria sair da sua rede.
{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": [
        "-y",
        "chrome-devtools-mcp@latest",
        "--isolated",
        "--no-usage-statistics",
        "--no-performance-crux"
      ]
    }
  }
}

Limitações

  • Suporte oficial é só Google Chrome e Chrome for Testing — outros navegadores baseados em Chromium (Edge, Brave etc.) podem funcionar, mas sem garantia nenhuma do projeto.
  • Categorias inteiras de ferramenta vêm desligadas por padrão e exigem flag explícita: debugging de memória/heap snapshot só ativa com --memoryDebugging, extensões do navegador com --categoryExtensions, integração com ferramentas de terceiro embutidas na própria página com --categoryExperimentalThirdParty. Se um cenário seu pedir uma dessas categorias e o agente disser que a ferramenta não existe, é provavelmente flag faltando, não bug.
  • Se você precisa que o agente teste um fluxo que exige login numa conta real, o perfil dedicado padrão nasce deslogado — ou você loga manualmente dentro dele antes (indo direto nesse perfil fora do agente), ou usa o modo --autoConnect/--browserUrl pra conectar numa instância de Chrome que você já abriu e já está logado (documentado no próprio README, fora do escopo deste tutorial).
  • Existe um modo --slim, com só 3 ferramentas (navegação, execução de script, screenshot) — útil se você só quer verificação visual básica e prefere reduzir a lista de ferramentas exposta ao agente.

Problemas comuns

  • "Failed to connect" logo depois de configurar — na maioria das vezes é Chrome não encontrado no PATH. Confirme que o Chrome está instalado normalmente (não só o Chromium de outro projeto) ou passe o caminho manual com a flag --executablePath.
  • O comando trava sem terminar — se você tirou o -y do npx ao adaptar algum exemplo, a primeira execução pode ficar esperando confirmação interativa pra instalar o pacote (o que trava um processo iniciado pelo Claude Code em segundo plano, sem terminal visível). Sempre mantenha o -y nos args.
  • Instalação via plugin (com skills) falha com erro de clone de repositório — o README oficial documenta isso como problema comum atrás de firewall corporativo/HTTPS restrito; a alternativa é usar o método de CLI (claude mcp add) descrito acima em vez do plugin.
  • O agente "não vê" a mudança que você acabou de salvar — lembre de pedir explicitamente pra recarregar a página (reload/navegar de novo) depois de editar o arquivo; o MCP não sabe sozinho que seu hot-reload já rodou.

Downloads

Preparamos um pacote de exemplo com as duas variações de configuração usadas neste tutorial — a padrão (recomendada pelo README oficial) e a "endurecida" de privacidade (com --isolated, --no-usage-statistics e --no-performance-crux já ligadas) — mais os comandos de claude mcp add comentados linha a linha. Baixe, escolha o arquivo .json que fizer sentido pro seu caso e copie pra .mcp.json na raiz do projeto (ou use os comandos do script pra configurar via CLI direto).

Links oficiais

Próximo passo

Se essa foi sua primeira conexão MCP no Claude Code, vale conhecer o conceito por trás antes de conectar o próximo servidor — leia o que é o Model Context Protocol e por que toda IA vai depender disso. Pra ir direto no passo a passo de conectar outras ferramentas (não só o Chrome) ao seu agente, tem também MCP na prática: conectando suas ferramentas à IA passo a passo.

Fora do site, o próximo passo mais direto é abrir a documentação oficial do chrome-devtools-mcp e testar você mesmo com um Chrome instalado — os dois cenários deste tutorial (edição + verificação visual, e trace de performance) rodam em poucos minutos assim que a conexão aparece como ✔ Connected.