Como usar o Playwright MCP no Claude Code para o agente abrir o navegador e conferir a tela

Muda o código, salva, abre o navegador na mão, vê que quebrou, volta pro chat e tenta descrever com palavras o que apareceu na tela

Esse vai e volta é o pedaço mais chato do vibe coding hoje

O Playwright MCP é um servidor MCP oficial da Microsoft, publicado no repositório microsoft/playwright-mcp e distribuído no npm como @playwright/mcp

Ele dá capacidade de automação de navegador para clientes MCP, e o Claude Code é um deles

Ou seja: o ciclo mudar, abrir e conferir passa a acontecer dentro da própria sessão 🙂

Pré-requisitos antes de instalar o Playwright MCP

Nada de PC da Nasa aqui, a lista é bem curtinha:

• Node.js 20 ou mais novo
• um cliente MCP (de novo: o Claude Code é um deles)
• os navegadores, que são baixados automaticamente no primeiro uso, sem instalação manual prévia

Essa última parte é massa, porque tu não precisa sair instalando browser na mão antes de testar qualquer coisa

E se a ideia é levar isso pra projeto de trabalho, vale saber que o repositório usa licença Apache-2.0

Como instalar e usar o Playwright MCP no Claude Code passo a passo

1. Registre o servidor no Claude Code

O comando oficial é esse:

claude mcp add playwright npx @playwright/mcp@latest

Repara na tag @latest, ela puxa a versão mais recente do pacote na hora de rodar

O erro comum deste passo: tentar em um Node antigo

O pré-requisito é Node.js 20 ou mais novo, então se estourar logo de cara, confere a versão do Node antes de sair caçando culpado no MCP

2. Escolha o escopo antes de sair usando

O Claude Code grava servidores MCP em escopo local por padrão, ou seja: só você, só no projeto atual

Se tu quer versionar a configuração e compartilhar com o time, existe o escopo de projeto, que grava um .mcp.json na raiz

claude mcp add --scope project playwright npx @playwright/mcp@latest

E se a ideia é ter o Playwright MCP disponível em todos os seus projetos, o escopo é o de usuário:

claude mcp add --scope user playwright npx @playwright/mcp@latest

As duas flags também aceitam a forma curta -s project e -s user

O erro comum deste passo: registrar no escopo local, abrir outro projeto no dia seguinte e achar que a instalação sumiu

Não sumiu, ela só está exatamente onde tu mandou ela ficar 😀

3. Confira a conexão com /mcp

Dentro da sessão do Claude Code, roda:

/mcp

Esse comando mostra o status dos servidores MCP conectados

O erro comum deste passo: pular a checagem, pedir "abre a página aí" e passar cinco minutos brigando com o prompt quando o problema era o servidor nem estar conectado

4. Peça a primeira navegação e entenda o par navigate + snapshot

Agora sim, pede pro agente abrir uma tela do teu projeto e descrever o que tem nela

Por baixo, ele usa duas ferramentas em sequência: browser_navigate pra ir até a página e browser_snapshot pra enxergar o que está lá

E aqui vem a parte mais importante de entender

"Enxergar" como? O Playwright MCP lê a árvore de acessibilidade da página, e não pixels

Ele devolve um snapshot estruturado com os elementos, seus papéis e seus textos, e cada elemento interativo vem com uma referência única

Se tu já mexeu com HTML semântico, a analogia é direta: é mais parecido com o agente ler a estrutura da tela do que olhar uma foto dela

Por isso a interação não depende de modelo de visão

O erro comum deste passo: pedir screenshot achando que o agente vai clicar a partir da imagem (tem uma seção inteira sobre isso mais pra frente)

5. Ajuste o modo de execução (headed x headless)

O navegador abre em modo visível (headed) por padrão

Se tu não quer janela pulando na tua frente, existe flag pra isso:

npx @playwright/mcp@latest --headless

O erro comum deste passo: rodar em headless e achar que travou porque nada apareceu

Não travou, tu que mandou ele ficar quietinho 😛

O que dá para pedir ao agente com o navegador aberto

A documentação do Claude Code cita esses casos de uso para a integração de navegador:

• testar web apps
• depurar com logs de console
• automatizar preenchimento de formulários
• extrair dados de páginas
• verificar design
• trabalhar com apps autenticados

E o ponto que amarra tudo: dá pra encadear ações do navegador com tarefas de código no mesmo fluxo

Na prática isso vira ferramenta com nome e sobrenome

Clicar é browser_click, digitar é browser_type, preencher formulário inteiro é browser_fill_form, marcar e desmarcar checkbox é browser_check e browser_uncheck

Pra ver o console da página tem o browser_console_messages, que é o que transforma "tá dando erro" em erro com mensagem de verdade

E browser_take_screenshot pra registrar a tela

O catálogo é bem completão: a documentação oficial fala em mais de 40 ferramentas, cobrindo navegação, formulários, mock de rede, storage, tracing e vídeo

Se tu já curte deixar o agente rodando tarefas sozinho, o navegador entra como mais um passo do fluxo, e não como uma ferramenta separada que tu abre do lado

Como manter login e sessão entre execuções (perfil persistente, isolado e modo extensão)

Esse é o atrito número um de quem testa app autenticado, então vale um bloco só pra ele

1. Perfil persistente é o padrão

O Playwright MCP mantém perfil persistente por padrão, preservando login e cookies entre sessões

O perfil fica em ms-playwright/mcp-{channel}-{workspace-hash}, dentro do diretório de cache da plataforma, com perfis separados por projeto

Tradução: tu loga uma vez e a próxima sessão já começa logada

2. Quando tu quer começar do zero

Tem hora que o estado guardado atrapalha, tipo testar onboarding de usuário novo

Pra isso existe o modo isolado, em que cada sessão começa limpa:

npx @playwright/mcp@latest --isolated

O erro comum deste passo: debugar por meia hora um fluxo de "primeiro acesso" com um perfil que já tinha cookie de sessão antiga

3. Modo extensão, pro SSO que não te deixa em paz

Tem o modo --extension, que conecta a abas já abertas do teu navegador

Ele reaproveita sessões logadas, cookies e extensões instaladas, e serve justamente pra pular fluxos de SSO e 2FA

Pra usar, é preciso ter a Playwright Extension instalada no Chrome ou no Edge

Sem canal especificado, a extensão conecta no Chrome por padrão

4. Navegador e configuração avançada

Os navegadores suportados são Chrome, Firefox, WebKit e Edge, e os valores aceitos na configuração são chrome, firefox, webkit e msedge

E quando a linha de comando começa a ficar comprida demais, dá pra jogar tudo em um arquivo JSON:

npx @playwright/mcp@latest --config caminho/para/config.json

Onde ainda sobra trabalho manual (e o que fazer)

Agora a parte honesta, porque integração de navegador não é varinha mágica

Sintoma: o agente tira o screenshot mas não consegue clicar

Causa: o screenshot não serve pra agir

A própria documentação do browser_take_screenshot avisa que não dá pra executar ações a partir dele

Solução: pedir browser_snapshot, que devolve a árvore de acessibilidade com papéis, textos e uma referência única por elemento interativo

Como prevenir: trata o screenshot como registro visual pra você, e o snapshot como o mapa que o agente usa pra clicar e digitar

Sintoma: a página "parece certa" pro agente e feia pra você

Causa: árvore de acessibilidade não é pixel

Coisa puramente visual, e conteúdo desenhado em canvas, não aparecem estruturados do jeito que um botão com papel e texto aparece

Solução: usar o screenshot pra conferência de layout e assumir esse pedaço como humano mesmo

Como prevenir: dividir o pedido em duas partes, uma de comportamento (fluxo, formulário, console) e outra de aparência, que continua passando pelo teu olho

Sintoma: funcionou ontem, hoje caiu na tela de login

Causa: estado de perfil e escopo mal escolhidos

Solução: conferir se tu está no perfil persistente (padrão) ou rodando com --isolated, e checar em qual escopo o servidor foi registrado

Como prevenir: decidir isso no começo do projeto, e não no meio do debug: escopo local pra brincar sozinho, .mcp.json com --scope project quando o time inteiro precisa do mesmo setup

Playwright MCP, Chrome DevTools MCP ou o Chrome nativo do Claude Code?

São três caminhos diferentes pro mesmo desejo de ver a tela, se liga na diferença:

Sobre a opção nativa, tem dois requisitos que pegam gente desprevenida: a extensão Claude in Chrome na versão 1.0.36 ou superior, e um plano direto da Anthropic (Pro, Max, Team ou Enterprise)

O /chrome também mostra status da conexão, gerencia permissões, reconecta a extensão e deixa escolher qual navegador usar

Vale a pena? Quando escolher cada caminho

Não tem vencedor absoluto aqui, tem perfil de uso

Playwright MCP se o que tu quer é o agente agindo como usuário, clicando, preenchendo formulário e passando por mais de um navegador, com fluxos que podem virar teste reaproveitável depois

Chrome nativo do Claude Code se tu já tem plano direto da Anthropic e quer o caminho mais curto: liga a extensão, roda /chrome e segue o jogo

Chrome DevTools MCP se a tua dor é investigação de performance e rede dentro de uma sessão real do Chrome

E o que não muda em nenhum dos três: o julgamento visual final continua sendo teu

O agente te diz que o botão existe, que o formulário enviou e que o console está limpo

Se aquilo ficou bonito, e se aquilo devia ter ido pro repositório, é outra conversa, do mesmo tipo daquelas que a gente precisa ter antes de soltar o agente no Git

Conclusão

O ganho real do Playwright MCP no Claude Code não é "IA que usa navegador", é o ciclo mudar, abrir e conferir acontecendo em um lugar só

Menos tu descrevendo bug por escrito, mais o agente olhando o resultado da mudança que ele mesmo fez

Próximo passo prático: roda o claude mcp add, confere com /mcp dentro da sessão e testa em uma tela do teu próprio projeto, de preferência uma que tu já sabe que está quebrada

Se for coisa de time, grava no .mcp.json com --scope project e todo mundo começa do mesmo ponto

Até o próximo post! 😀