Como usar o Playwright MCP com o Claude Code: automação de navegador e configuração de proxy

Scripts padrão de scraping e de QA costumam quebrar assim que um site atualiza o layout ou renomeia uma classe CSS. Conectar o pacote playwright-mcp ao Claude Code CLI resolve esse problema. Por meio do Model Context Protocol (MCP), o navegador envia um mapa de texto limpo da página diretamente ao agente de IA. Você não precisa mais procurar seletores CSS manualmente nem enviar screenshots pesados a um modelo de visão. Engenheiros de QA, desenvolvedores de scrapers e analistas controlam Chromium, Firefox, WebKit e Microsoft Edge diretamente pelo terminal, direcionando o tráfego por proxies.

Resumo rápido do fluxo de trabalho com Claude e Playwright MCP

• Como funciona: o pacote playwright-mcp envia ao Claude Code um snapshot de acessibilidade leve do playwright mcp (browser_snapshot) em vez de imagens pesadas, reduzindo o consumo de tokens em até 80%.

• Configuração com um único comando: executar claude mcp add playwright -- npx @playwright/mcp@latest registra o servidor oficial do playwright mcp para uma única pasta, para um repositório compartilhado da equipe ou globalmente em todo o computador.

• Isolamento de perfis: combinar a flag --isolated com um arquivo de cookies --storage-state (ou pastas --user-data-dir separadas) permite executar várias janelas do navegador em paralelo sem erros de bloqueio de arquivos.

• Roteamento por proxy: passar --proxy-server e HTTP_PROXY no arquivo .mcp.json direciona o tráfego do navegador por proxies móveis LTE/5G, proxies residenciais ISP estáticos ou proxies residenciais rotativos.

• Verificação de IP antes da execução: antes de iniciar a tarefa, verifique a reputação do seu IP no verificador de Fraud Score integrado ao painel de controle do CyberYozh App.

👉 Explore o catálogo de proxies do CyberYozh App por país e tipo de provedor

O que o Playwright MCP faz dentro do navegador

Em que o playwright mcp difere das ferramentas de navegador mais antigas? Os agentes de IA visuais tradicionais capturavam imagens em tela cheia e clicavam em botões usando coordenadas aproximadas de pixels X e Y. Sempre que um banner promocional aparecia ou o layout responsivo mudava, o clique errava o alvo.

O servidor oficial do playwright mcp, da Microsoft (@playwright/mcp), lê a árvore de acessibilidade do navegador em vez de capturar pixels. Chamar browser_snapshot retorna um mapa de texto estruturado de todos os elementos interativos da página. Cada botão, link ou campo de entrada recebe uma tag de referência exata, como textbox "Search catalog" [ref=e5] ou button "Apply filter" [ref=e12]. Com um snapshot de acessibilidade do playwright mcp, o Claude Code passa ref=e5 diretamente para browser_type ou browser_click, sem adivinhar coordenadas. O servidor também inspeciona o tráfego de API em segundo plano (browser_network_requests), lê os logs do console (browser_console_messages), alterna entre abas e exporta PDFs ou screenshots (browser_pdf_save, browser_take_screenshot).

Esse fluxo conecta três etapas da coleta automatizada de dados. O web scraping padrão baixa o código HTML bruto, o screen scraping lê os dados visuais renderizados no navegador depois da execução do JavaScript, e o parsing de dados extrai campos estruturados para CSV, Excel ou JSON. Com o playwright-mcp, o agente lê a árvore DOM ativa depois que o JavaScript termina a renderização e extrai os dados estruturados imediatamente.

👉 Conheça a infraestrutura de proxies para agentes de IA e automação de navegador no CyberYozh App

Como usar o Playwright MCP com o Claude Code no terminal

Antes de testar o playwright mcp com o Claude Code em sites reais, verifique três pré-requisitos na sua máquina: Node.js 18 ou superior (recomenda-se Node.js 20+ LTS), o Claude Code CLI autenticado (@anthropic-ai/claude-code) e credenciais de proxy ativas para evitar limitação de taxa.

Como adicionar o Playwright MCP ao Claude Code: três modos de configuração

Você pode adicionar o Playwright MCP ao Claude Code com um único comando, usando a flag --scope para definir o nível da configuração: local (pasta atual), project (repositório compartilhado da equipe) ou user (perfil global). As configurações da pasta local sempre prevalecem sobre as do projeto e as globais.

Execute os comandos abaixo para verificar as versões instaladas, pré-carregar o binário do Chromium e registrar o servidor:

# 1. Check installed Node.js and Claude Code versions
node --version
claude --version

# 2. Pre-install the package and Chromium browser
npx @playwright/mcp@latest --version
npx playwright install chromium

# 3. Register the server (choose one of the three options)
# Option A: Only for the currently open folder
claude mcp add playwright -- npx @playwright/mcp@latest

# Option B: Globally for all your projects on this computer
claude mcp add playwright --scope user -- npx @playwright/mcp@latest

# Option C: Create a shared .mcp.json file in the project root for your team
claude mcp add playwright --scope project -- npx @playwright/mcp@latest

# 4. Verify the list of connected MCP servers
claude mcp list

Depois de executar claude mcp add playwright, você também pode instalar a versão da comunidade ExecuteAutomation (@executeautomation/playwright-mcp-server), com presets de viewport para 143 modelos de smartphones e desktops. Se você prefere fazer scraping de sites pelo Claude AI sem editar arquivos de configuração manualmente, o nosso Yozh Scraper no GitHub, de código aberto, direciona o tráfego automaticamente pelos seus proxies do CyberYozh App.

👉 Alugue proxies móveis LTE/5G a partir de $1.70/dia com tráfego ilimitado

Configuração de proxy do Playwright MCP no .mcp.json

Quando uma sessão do claude playwright mcp verifica landing pages de anúncios localizadas, compara preços regionais ou faz scraping de catálogos de produtos, requisições rápidas a partir de um único IP residencial ou de escritório disparam CAPTCHAs. Adicionar uma configuração de proxy do playwright mcp no arquivo .mcp.json (ou ~/.claude.json) direciona o tráfego do navegador pela região desejada:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "-y",
        "@playwright/mcp@latest",
        "--browser",
        "chromium",
        "--isolated",
        "--proxy-server=http://proxy.cyberyozh.com:8080"
      ],
      "env": {
        "HTTP_PROXY": "http://username:password@proxy.cyberyozh.com:8080",
        "HTTPS_PROXY": "http://username:password@proxy.cyberyozh.com:8080",
        "PLAYWRIGHT_MCP_PING_TIMEOUT_MS": "15000"
      }
    }
  }
}

Observação: o endereço do servidor (proxy.cyberyozh.com), a porta (8080), o nome de usuário e a senha acima são apenas exemplos. Substitua-os pelo host, pela porta e pelas credenciais de acesso do cartão do seu proxy no painel de controle do CyberYozh App.

Como gerenciar perfis do navegador, cookies e a persistência do IP do proxy

Para evitar falhas por bloqueio de perfil em execuções paralelas e redefinições inesperadas de sessão, mantenha dois mecanismos separados:

1. Onde ficam armazenados os cookies e as sessões do navegador: por padrão, o playwright-mcp salva cookies e dados dos sites em uma única pasta compartilhada no disco. Abrir um segundo terminal do Claude Code apontando para a mesma pasta causa um erro de bloqueio. Para executar vários navegadores em paralelo, inicie um perfil isolado do playwright mcp com a flag --isolated (que cria um perfil limpo na memória) e injete os cookies de login salvos com --storage-state=./auth.json. Se você precisa de um perfil permanente em disco em vez de um perfil isolado do playwright mcp em memória, atribua uma pasta dedicada a cada projeto com --user-data-dir.

2. Como manter o IP do proxy consistente: cookies e IPs de proxy funcionam de forma independente. Um IP estático não renova um token de cookie expirado, e cookies salvos não evitam um logout se o seu IP externo mudar no meio do checkout. Observe também uma limitação do Chromium: a flag --proxy-server aceita nome de usuário e senha apenas por HTTP/HTTPS. Conexões SOCKS5 diretas no Chromium funcionam apenas com autorização por IP (whitelist) sem senha no seu painel de controle, enquanto o SOCKS5 protegido por senha exige um proxifier local.

👉 Escolha proxies residenciais rotativos a partir de $4.00/GB com sticky sessions de até 24 horas

Quais proxies do CyberYozh App escolher para o playwright-mcp

A linha de proxy ideal depende dos sites de destino e da duração da sessão. A plataforma CyberYozh App oferece quatro opções para automação de navegador:

• Proxies móveis LTE/4G/5G (a partir de $1.70/dia com tráfego ilimitado): funcionam em modems físicos e com cartões SIM reais de operadoras. Como as redes móveis usam CGNAT, centenas de assinantes comuns de smartphones compartilham um único IP da operadora. Filtros antifraude e mecanismos de busca como o Google têm muito menos probabilidade de restringir esse endereço durante scraping de buscas em múltiplas threads ou verificações de anúncios. Nos planos privados, você troca o IP por um link do painel de controle ou pela REST API, enquanto os planos compartilhados rotacionam em um temporizador de 5 ou 30 minutos. Suportam HTTP/HTTPS, SOCKS5, UDP, configurações VPN/VLESS e troca do fingerprint de SO TCP/IP. Como as torres das operadoras renovam periodicamente os leases de IP do lado delas, alugue primeiro um plano diário para testar a duração da sessão antes de execuções de várias horas.

• Proxies residenciais ISP estáticos (a partir de $5.29/mês com tráfego ilimitado): fornecem um IP residencial dedicado de um provedor de internet (ISP) real durante todo o período de aluguel, com 99.9% de uptime e suporte a HTTP/HTTPS e SOCKS5. Feitos para sessões de várias semanas e meses em projetos de clientes e marcas, painéis de anúncios, painéis administrativos e lojas online. Agências vinculam um proxy ISP estático a uma pasta de perfil de navegador dedicada (--user-data-dir) por cliente, para que sessões e cookies nunca se misturem.

• Proxies residenciais rotativos (a partir de $4.00/GB, mínimo de 3 GB; até $2.50/GB a partir de 100 GB): dão acesso a mais de 100M de IPs residenciais em mais de 195 países. Incluem segmentação gratuita por país, estado/região e cidade, filtragem avançada de IP antes da atribuição, 99.9% de uptime e taxa de sucesso de requisições de até 99.99%. Use rotação por requisição para scraping de catálogos ou mantenha um IP por até 24 horas com sticky sessions. Os gigabytes não utilizados passam para o mês de cobrança seguinte, e o Mass Credentials Generator e a REST API simplificam configurações em massa.

• Proxies de datacenter (servidor) (a partir de $1.77/mês): oferecem canais IPv4/IPv6 dedicados e compartilhados, com tráfego ilimitado nos planos dedicados e 99.99% de uptime, para scraping de alta velocidade de páginas públicas, monitoramento de disponibilidade e testes de API.

👉 Selecione proxies com tráfego ilimitado para web scraping e automação de navegador

Verificação da reputação do IP via Fraud Score e correção de erros comuns

Antes de adicionar um proxy à configuração do playwright-mcp, verifique o IP no verificador de risco Fraud Score integrado ($0.15 por verificação de IP, ou $19.00/mês por 1,500 verificações de IP, 1,500 verificações de número de telefone e 500 verificações de cartão bancário, com economia de até $600/mês). A ferramenta consulta IPQualityScore (IPQS), CyberSource, ThreatMetrix, Stripe Radar, PerimeterX e 118 blacklists OSINT, mostrando o rótulo ISP/ASN, a pontuação de risco e o status de Abuse Velocity antes de você iniciar o navegador.

Para testar a conexão, inicie o cliente com MCP_TIMEOUT=10000 claude para que o npx tenha tempo suficiente para baixar o pacote na primeira execução. Digite /mcp no chat para confirmar que o playwright exibe o status verde connected. No primeiro prompt, cite a ferramenta explicitamente para que o Claude abra o navegador em vez de escrever código de script:

Use Playwright MCP: open https://app.cyberyozh.com/checkers/, read the page structure, and list the available checkers for verifying IP addresses, phone numbers, and cards.

Se os seus testes automatizados cobrem formulários de cadastro por SMS ou fluxos de checkout, você pode alugar números de telefone virtuais para receber SMS e emitir cartões virtuais no mesmo painel de controle do CyberYozh App.

👉 Verifique a reputação do IP e o Fraud Score antes de iniciar o navegador

Primeiros passos com automação de navegador no Claude Code

Combinar o playwright-mcp com o Claude Code permite controlar um navegador real com comandos de texto simples no terminal: o agente abre páginas, localiza elementos pela árvore de acessibilidade e extrai dados sem seletores frágeis. Associar essa configuração a proxies móveis LTE/5G, ISP estáticos ou residenciais rotativos do CyberYozh App mantém estáveis os seus testes regionais, verificações de lojas e scraping de catálogos em qualquer localização.

👉 Alugue números de telefone virtuais para verificação por SMS ao testar fluxos de cadastro