Configuração

Matthias Rohmer
José Luis Zapata

Você pode configurar o Chrome DevTools para agentes para personalizar a interação com o navegador, quais ferramentas estão ativadas e como ele processa os dados.

Configure o servidor transmitindo flags de linha de comando na matriz args do arquivo de configuração do cliente do Protocolo de Contexto de Modelo (MCP). Normalmente, esse é o arquivo config.json.

Por exemplo, para executar o Chrome no modo headless e usar o canal Canary, use a seguinte configuração:

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

Cenários de configuração comuns

Os cenários a seguir descrevem maneiras comuns de configurar o Chrome DevTools para agentes.

Executar no modo headless

Para realizar tarefas em segundo plano sem uma janela de navegador visível, execute o Chrome no modo headless (sem interface). Adicione a flag --headless aos argumentos do servidor.

Conectar a uma sessão de navegador atual

Por padrão, o DevTools para agentes inicia uma nova instância do Chrome. No entanto, é possível conectar o agente a uma sessão de navegador atual. Isso é útil se o agente precisar investigar um problema em uma sessão já iniciada (por exemplo, se você já fez login).

É possível se conectar a uma sessão atual de duas maneiras:

Conexão automática (Chrome 144 ou mais recente)

Se você usar a flag --autoConnect, o servidor MCP se conectará automaticamente a uma instância ativa do Chrome.

  1. No navegador Chrome em execução, acesse chrome://inspect/#remote-debugging e ative a depuração remota.
  2. Adicione --autoConnect à configuração do MCP: json "args": ["chrome-devtools-mcp@latest", "--autoConnect"]
  3. Quando o agente tentar se conectar, o Chrome vai mostrar uma caixa de diálogo pedindo permissão. Clique em Permitir.

Conexão manual

Se não for possível usar --autoConnect (por exemplo, em um ambiente em sandbox), você poderá iniciar o Chrome manualmente com uma porta de depuração e se conectar usando --browser-url.

  1. Inicie o Chrome no terminal com a depuração remota ativada e um diretório de dados do usuário personalizado.
    • macOS: shell /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-profile-stable
    • Windows: shell start chrome --remote-debugging-port=9222 --user-data-dir=%TEMP%\chrome-profile-stable
    • Linux: shell google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-profile-stable
  2. Configure o agente para se conectar a essa porta: json "args": ["chrome-devtools-mcp@latest", "--browser-url=http://127.0.0.1:9222"]

Referência das opções de configuração

As seções a seguir listam as flags de configuração disponíveis. Para conferir as opções e atualizações mais recentes, consulte o repositório do Chrome DevTools MCP no GitHub.

Opções de conexão

Use essas opções para configurar como o servidor se conecta ao Chrome.

Sinalização Tipo Padrão Descrição
--autoConnect ou --auto-connect booleano false Conecta-se automaticamente a uma instância do Chrome (144 ou mais recente) em execução local. Exige que a depuração remota seja ativada usando chrome://inspect/#remote-debugging.
--browserUrl ou --browser-url
-u		 string false Conecte-se a uma instância do Chrome em execução e depurável (por exemplo, http://127.0.0.1:9222).
--wsEndpoint ou --ws-endpoint
-w		 string false Endpoint do WebSocket para se conectar a uma instância do Chrome em execução (por exemplo, ws://127.0.0.1:9222/devtools/browser/<id>). Alternativa para --browserUrl.
--wsHeaders ou --ws-headers string false Cabeçalhos personalizados para conexão WebSocket no formato JSON (por exemplo, '{"Authorization":"Bearer token"}'). Funciona apenas com --wsEndpoint.

Opções de inicialização do navegador

Essas opções são aplicadas quando o servidor MCP inicia o Chrome.

Sinalização Tipo Padrão Descrição
--headless booleano false Executa o Chrome no modo headless (sem interface).
--channel string stable Especifica o canal do Chrome a ser usado. Opções: canary, dev, beta e stable.
--executablePath ou --executable-path
-e		 string false Caminho para um executável personalizado do Chrome.
--userDataDir ou --user-data-dir string Consulte a descrição Caminho para o diretório de dados do usuário. O padrão é $HOME/.cache/chrome-devtools-mcp/chrome-profile$CHANNEL_SUFFIX_IF_NON_STABLE.
--isolated booleano false Cria um diretório de dados do usuário temporário que é limpo automaticamente quando o navegador é fechado.
--viewport string false Tamanho inicial da janela de visualização (por exemplo, 1280x720). No modo headless, o tamanho máximo é 3840x2160.
--proxyServer ou --proxy-server string false Configuração do servidor proxy transmitida ao Chrome.
--chromeArg ou --chrome-arg matriz false Argumentos extras a serem transmitidos ao Chrome.
--ignoreDefaultChromeArg ou --ignore-default-chrome-arg matriz false Desative explicitamente os argumentos padrão do Chrome.

Opções de segurança e privacidade

Use essas opções para gerenciar as configurações de segurança e a privacidade de dados.

Sinalização Tipo Padrão Descrição
--acceptInsecureCerts ou --accept-insecure-certs booleano false Ignora erros relacionados a certificados autoassinados e expirados. Use com cuidado.
--blockedUrlPattern ou --blocked-url-pattern matriz false Restringe o acesso à rede bloqueando padrões de URL especificados (usa URLPattern). Bloqueia navegações e sub-recursos.
--allowedUrlPattern ou --allowed-url-pattern matriz false Restringe o acesso à rede permitindo apenas padrões de URL especificados. Requer o Chrome 149 ou mais recente.
--redactNetworkHeaders ou --redact-network-headers booleano false Edita cabeçalhos de rede sensíveis antes de retorná-los ao cliente.
--usageStatistics ou --usage-statistics booleano true Ativa a coleta de estatísticas de uso para melhorar a ferramenta. Também pode ser desativado usando as variáveis de ambiente CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS ou CI.
--performanceCrux ou --performance-crux booleano true Envia URLs de rastreamentos de performance para a API CrUX do Google para buscar dados de experiência do usuário real.

Categorias de recursos

É possível ativar ou desativar grupos de ferramentas usando essas flags.

Sinalização Tipo Padrão Descrição
--categoryEmulation ou --category-emulation booleano true Ativa ferramentas relacionadas à emulação.
--categoryNetwork ou --category-network booleano true Ativa ferramentas relacionadas à rede.
--categoryPerformance ou --category-performance booleano true Ativa ferramentas relacionadas à performance.
--categoryExtensions ou --category-extensions booleano false Ativa ferramentas relacionadas a extensões. Só é compatível com conexão de pipe.
--categoryExperimentalThirdParty ou --category-experimental-third-party booleano false Ativa as ferramentas para desenvolvedores de terceiros expostas pela página inspecionada.
--categoryExperimentalWebmcp ou --category-experimental-webmcp booleano false Ativa ferramentas de depuração do WebMCP. Requer o Chrome 149 ou mais recente com os recursos do WebMCP ativados.
--memoryDebugging ou --memory-debugging booleano false Ativa ferramentas de depuração de memória.

Opções de captura de tela

Use essas opções para personalizar como o agente captura capturas de tela.

Sinalização Tipo Padrão Descrição
--screenshotFormat ou --screenshot-format string false Substitui o formato de saída padrão (png). Opções: jpeg, png e webp. Os formatos jpeg e webp são menores, o que ajuda a reduzir o tamanho do contexto em conversas de IA.
--screenshotQuality ou --screenshot-quality número false Substitui a qualidade de compactação (0 a 100) para jpeg e webp.
--screenshotMaxWidth ou --screenshot-max-width número false Largura máxima em pixels. Capturas de tela maiores são reduzidas.
--screenshotMaxHeight ou --screenshot-max-height número false Altura máxima em pixels. Capturas de tela maiores são reduzidas.

Opções experimentais

Use essas opções para ativar recursos experimentais em desenvolvimento.

Sinalização Tipo Padrão Descrição
--experimentalPageIdRouting ou --experimental-page-id-routing booleano false Expõe pageId em ferramentas com escopo de página para rotear solicitações em sessões de agentes simultâneas.
--experimentalDevtools ou --experimental-devtools booleano false Ativa a automação em destinos do DevTools.
--experimentalVision ou --experimental-vision booleano false Ativa ferramentas baseadas em coordenadas (por exemplo, click_at). Geralmente requer um modelo de uso do computador que possa produzir coordenadas precisas analisando capturas de tela.
--experimentalStructuredContent ou --experimental-structured-content booleano false Mostra conteúdo formatado estruturado.
--experimentalIncludeAllPages ou --experimental-include-all-pages booleano false Inclui todos os tipos de páginas (por exemplo, WebViews e páginas em segundo plano).
--experimentalScreencast ou --experimental-screencast booleano false Expõe ferramentas de screencast (requer ffmpeg no PATH).
--experimentalFfmpegPath ou --experimental-ffmpeg-path string false Caminho para o executável ffmpeg.

Outras opções

Use essas opções para configurar o registro ou ativar um conjunto simplificado de ferramentas.

Sinalização Tipo Padrão Descrição
--slim booleano false Expõe um conjunto reduzido de três ferramentas (navegação, execução de scripts e capturas de tela). Útil para tarefas básicas do navegador.
--logFile ou --log-file string false Caminho para um arquivo em que os registros de depuração serão gravados.

Variáveis de ambiente

Também é possível usar as seguintes variáveis de ambiente para configurar o servidor:

  • CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS: se definido, desativa a coleta de estatísticas de uso (equivalente a --no-usage-statistics).
  • CHROME_DEVTOOLS_MCP_NO_UPDATE_CHECKS: se definido, desativa as verificações periódicas de atualizações.
  • CI: se definido, desativa a coleta de estatísticas de uso.
  • DEBUG: defina como * para ativar o registro de depuração detalhado (funciona em conjunto com --logFile).