Playwright MCP no Claude Code: como fazer o agente abrir o navegador e conferir a tela

O agente edita o arquivo, diz que resolveu e segue a vida

Só que ele não viu a tela

Esse é o ponto cego do vibe coding em front: o modelo mexe no CSS, ajusta o componente, jura que arrumou, e quem abre o navegador pra descobrir que o botão continua sumido é você. O Playwright MCP existe justamente pra fechar esse buraco. É um servidor MCP oficial da Microsoft, mantido no repositório microsoft/playwright-mcp e publicado no npm como @playwright/mcp, que entrega automação de navegador pra clientes MCP, com o Claude Code incluso na lista

Neste post tu vai ver a instalação passo a passo, as flags que importam, o que muda de verdade no ciclo de correção de front e onde isso só queima token à toa 🙂

O que você precisa antes de instalar:

A lista é curta, e é bom conferir antes pra não brigar com erro besta depois

• Node.js 20 ou mais novo, que é o requisito de runtime pra instalar o Playwright MCP
• Claude Code instalado na máquina, afinal é ele quem vai carregar o servidor
• Nada de instalar navegador na mão: o browser usado pelo Playwright MCP é baixado automaticamente no primeiro uso
• Uma decisão de escopo, que é onde o registro do servidor vai morar (local é o padrão, e existem --scope user e --scope project)

Esse último item parece detalhe, mas é o que mais gera confusão depois. Já volto nele

Pré-inscrição Formação Claude Code

Domine o Claude Code do básico ao avançado

Você vai aprender a criar sistemas completos com Claude Code, sem precisar ser programador. Inscreva-se para ter acesso a um desconto de lançamento e bônus especiais!

Quero minha vaga

Como instalar o Playwright MCP no Claude Code passo a passo:

Bora ver na prática?

1. Registre o servidor no Claude Code com o comando oficial

   claude mcp add playwright npx @playwright/mcp@latest

O erro comum deste passo: Node antigo. Se a sua máquina ainda está numa versão anterior à 20, atualiza antes de tentar, porque o requisito de runtime é Node.js 20 ou mais novo

2. Escolha o escopo com consciência. O local é o padrão: fica privado a você, só vale no projeto atual e é gravado em ~/.claude.json sob o caminho daquele projeto. Com --scope user o servidor passa a valer pra todos os seus projetos. Com --scope project ele é compartilhado com o time através de um arquivo .mcp.json na raiz, que entra no repositório e é lido pelo Claude Code na inicialização da sessão

O erro comum deste passo: instalar no escopo padrão, abrir outro projeto no dia seguinte e achar que o Playwright MCP evaporou. Ele não sumiu, ele só é local mesmo

E o .mcp.json versionado tem um efeito colateral massa: a configuração vira parte do repositório, na mesma linha de quando você quer que o agente respeite o padrão de código do projeto em vez de reinventar tudo de novo

3. Ou configure na mão, se preferir o JSON explícito. Essa forma é equivalente e vale em qualquer cliente MCP

   {
     "mcpServers": {
       "playwright": {
         "command": "npx",
         "args": ["@playwright/mcp@latest"]
       }
     }
   }

4. Reabra a sessão do Claude Code. O servidor fica disponível na próxima sessão, não naquela que está aberta

O erro comum deste passo (e talvez o mais comum de todos): rodar o comando, olhar pra sessão atual, não ver ferramenta nenhuma e concluir que deu errado. Fecha e abre de novo, beleza? 😀

5. Valide com o teste que a própria documentação sugere: peça pro agente navegar até https://demo.playwright.dev/todomvc e adicionar alguns itens de tarefa. Se ele abrir, digitar e listar o que ficou na tela, tá funcionando

Tem ainda um atalho pra quem prefere plugin a comando: o marketplace oficial gerenciado pela Anthropic tem um plugin de Playwright, instalável com /plugin install playwright@claude-plugins-official. Ele vive no repositório anthropics/claude-plugins-official, na pasta external_plugins/playwright

Flags úteis: janela visível, headless, sessão limpa e config em arquivo

Depois que roda, vem o ajuste fino. Essas são as flags que mudam o dia a dia

1. --headless pra rodar sem janela. Por padrão o Playwright MCP abre em modo headed, ou seja, janela visível, e sinceramente isso é ótimo no começo: tu vê o agente clicando, e entende o que ele tá fazendo. Quando o fluxo já é confiável (ou quando é CI), passa --headless

2. --isolated pra cada sessão começar limpa, e --storage-state pra carregar um estado inicial. Esse par é o que resolve tela que exige login

O erro comum deste passo: mandar o agente conferir uma tela logada sem estado inicial nenhum. Ele vai abrir, bater na tela de login e ficar parado ali, achando que a aplicação é aquilo

3. --config pra configuração avançada em arquivo, quando as flags soltas começam a virar uma linha quilométrica

   npx @playwright/mcp@latest --config path/to/config.json

4. --port pra modo HTTP. Por padrão o servidor roda localmente como processo na sua máquina usando transporte stdio, que é o que a maioria quer. O modo HTTP entra em cena em setup remoto ou Docker

O que muda no ciclo de correção de front (e onde vira gasto à toa)

Agora o que interessa: por que isso muda alguma coisa?

Porque o agente para de entregar o arquivo e torcer

As ferramentas que fazem o trabalho:

• browser_navigate abre a URL
• browser_click clica no elemento
• browser_snapshot devolve a árvore de acessibilidade da página
• browser_console_messages traz as mensagens do console
• browser_network_requests lista as requisições de rede desde o carregamento

Junta tudo e o loop fica editar, abrir, conferir, no lugar de editar e mandar o print pra você conferir

E o screenshot? Aqui tem um mal-entendido que vale desfazer. Screenshot não é o mecanismo primário de interação: o browser_take_screenshot faz parte do vision mode, que adiciona ferramentas baseadas em coordenadas pra elementos que não aparecem na árvore de acessibilidade. O padrão é o snapshot, uma árvore estruturada de elementos acessíveis com refs pra interação, apontada pela documentação como mais confiável e mais econômica em tokens na maioria das aplicações web. E o melhor: não exige modelo de visão

Onde vale de verdade:

• Bug que só aparece na interação, aquele que não dá pra ver lendo o componente
• Fluxo de várias telas, onde o estado de uma etapa afeta a próxima
• Erro que só sai no console de JS ou numa requisição quebrada na rede
• Checagem de estado depois de um clique ("o modal fechou mesmo?", "o item entrou na lista?")

Onde vira gasto à toa:

• Mudança óbvia de CSS ou de texto. Abrir navegador pra trocar um padding é usar canhão pra matar mosquito
• Caso que o teste automatizado já cobre. Se o assert existe e roda, deixa ele trabalhar
• Contexto: definições de ferramentas de servidores MCP entram no contexto do modelo e custam tokens. O Claude Code tem um mecanismo de tool search que adia essas definições quando o total passa de um limite, deixando só os nomes no contexto até a ferramenta ser chamada de fato, o que ajuda bastante

Mesmo assim, ligar servidor MCP por reflexo é uma das formas mais fáceis de inflar conta, e vale o mesmo raciocínio de economizar tokens no Claude Code: liga o que o trabalho de hoje pede, não o catálogo inteiro

Playwright MCP ou Claude in Chrome: qual usar

O Playwright MCP não é o único jeito de dar navegador pro Claude Code. Existe também a integração nativa com a extensão Claude in Chrome, que dá automação de navegador a partir do CLI

Se liga na diferença:

Pra saber se a integração nativa tá de pé, o /chrome é o lugar: funcionando, ele exibe Status: Enabled e Extension: Installed

Qual dos dois faz mais sentido no seu dia

Não tem vencedor absoluto aqui, tem contexto

Playwright MCP quando você quer sessão limpa e repetível, quando precisa rodar headless (CI, servidor, Docker com --port) ou quando quer que o time inteiro herde a mesma configuração pelo .mcp.json versionado no repositório

Claude in Chrome quando o que você precisa conferir já está no seu navegador logado, com as suas abas e as suas credenciais, e você tem plano direto da Anthropic

E agora a ressalva que ninguém gosta de ler, mas que é importante: existe uma discussão de segurança aberta no repositório oficial, a issue #1479 em microsoft/playwright-mcp, sobre injeção indireta de prompt via accessibility snapshots em sessões de navegador MCP. Traduzindo pro nosso português: o conteúdo da página que o agente lê vira texto no contexto do modelo. Ou seja, tome cuidado com página não confiável, porque texto no contexto é texto que o modelo pode acabar tratando como instrução

Sessão isolada e alvo conhecido não é frescura, é higiene

Próximo passo

O ganho aqui não é "o Claude Code agora abre navegador", isso é só o meio

O ganho é o agente verificar o resultado antes de dizer que arrumou, fechando o ciclo de correção de front sem você virar o robô de conferência dele 😀

Então o próximo passo é bem concreto: roda o claude mcp add playwright npx @playwright/mcp@latest, reabre a sessão, valida no TodoMVC e, no próximo bug de front que aparecer, pede explicitamente pro agente abrir a tela, clicar no que reproduz o problema e ler o console antes de propor qualquer correção

A diferença na primeira tentativa já dá pra sentir…

até o próximo post!