Como Usar Claude Code com Playwright MCP: Um Guia Completo de Configuração

O que é Playwright MCP?

O servidor Playwright MCP oferece a qualquer cliente Model Context Protocol poderes de automação de navegador. Em vez de pedir a uma IA para “olhar” pixels, o servidor retorna snapshots estruturados de acessibilidade da página, e o modelo interage com elementos por ID de referência. Isso torna o loop rápido, determinístico e livre de sobrecarga de modelo de visão. Funciona com VS Code, Cursor, Windsurf, Claude Desktop, Claude Code e qualquer outro cliente MCP.

Para Claude Code em particular, isso significa que o agente em seu terminal agora pode abrir um navegador, clicar, preencher formulários, simular requisições de rede, capturar capturas de tela e até executar scripts Playwright personalizados — tudo orientado por prompts em linguagem natural.

Pré-requisitos

Antes de começar, certifique-se de que você tem:

• Node.js 18 ou mais recente instalado
• Claude Code instalado e conectado (execute claude em seu terminal para verificar)
• Um terminal com o qual você se sinta confortável trabalhando

É isso — Playwright MCP baixa seus próprios binários de navegador na primeira execução.

Pronto para expandir seu negócio?

Comece seu teste gratuito hoje e veja resultados em dias.

Solicitar demo Entrar

Configurando a Integração Playwright MCP

Conectar Playwright MCP ao Claude Code é um comando único. Siga estas etapas para configurá-lo:

Adicione o Servidor Playwright MCP

Abra seu terminal e execute:

claude mcp add playwright npx @playwright/mcp@latest

Isso registra um novo servidor MCP chamado playwright que Claude Code inicia via npx sempre que precisa de ferramentas de navegador. A primeira invocação baixa o pacote e os binários de navegador necessários, portanto aguarde um minuto na primeira vez.

Verifique a Conexão

Inicie uma nova sessão de Claude Code e execute o comando /mcp:

claude

/mcp

Você deve ver playwright listado como um servidor conectado, juntamente com as ferramentas que ele expõe (navegação, clique, digitação, capturas de tela, simulação de rede e muito mais).

Opcional: Use uma Configuração JSON em Vez Disso

Se você preferir editar arquivos de configuração diretamente, o mesmo servidor pode ser adicionado a ~/.claude.json (ou um .mcp.json com escopo de projeto) usando o formato MCP padrão:

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

Reinicie Claude Code após editar o arquivo e o servidor aparecerá em /mcp.

Sua Primeira Automação de Navegador em Claude Code

Com o servidor conectado, seus prompts agora podem dirigir um navegador real. Tente a interação canônica primeiro da documentação do Playwright:

Navigate to https://demo.playwright.dev/todomvc and add a few todo items.

Claude Code abrirá o navegador, solicitará um snapshot de acessibilidade da página, localizará a entrada por sua referência de elemento, digitará cada tarefa e confirmará o resultado para você no terminal.

Aviso sobre qual navegador abre: por padrão, isso inicia o Chromium em modo com interface gráfica. Para alterar, adicione flags aos args na sua configuração MCP e reinicie Claude Code: --headless para ocultar a janela, ou --browser=firefox|webkit|msedge para alternar mecanismos.

Como Funcionam os Snapshots de Acessibilidade

Quando uma ferramenta Playwright MCP é executada, ela retorna um snapshot estruturado da página — funções de elemento, conteúdo de texto e IDs de referência — em vez de pixels. Claude lê o snapshot e usa referências como ref=e5 para digitar na caixa de texto ou ref=e10 para alternar a caixa de seleção. Sem pressionamento de pixel, sem seletores CSS frágeis — apenas estado estruturado da página que o modelo pode raciocinar.

Junte-se à nossa newsletter

Receba gratuitamente as últimas dicas, tendências e ofertas.

Endereço de e-mail

Inscrever-se

Capacidades Principais que Você Pode Usar do Claude Code

Depois que Playwright MCP está configurado, os mesmos prompts que você daria a um colega funcionam em Claude Code:

• Navegação: “Vá para example.com”, “volte”, “recarregue a página”.
• Clique e digitação: “Clique no botão Enviar”, “preencha o campo de email com test@example.com ”.
• Capturas de tela: “Tire uma captura de tela da seção de preços”.
• Teclado e mouse: Pressione teclas, passe o mouse, arraste e solte.
• Abas e diálogos: Abra novas abas, alterne entre elas, aceite ou rejeite popups.
• Monitoramento de rede: “Liste as requisições feitas desde o carregamento da página”.
• Simulação de API: “Simule o endpoint /api/users para retornar um array vazio”.
• Estado de armazenamento: Salve sessões autenticadas em um arquivo e recarregue-as posteriormente.

Para fluxos de trabalho que precisam de mais de uma única chamada de ferramenta, você pode pedir ao Claude Code para invocar browser_run_code e executar um script Playwright inline — útil para asserções, extração de dados ou qualquer coisa que se beneficie de algumas linhas de código imperativo.

Opções de Configuração Úteis

Playwright MCP tem um punhado de flags que vale a pena conhecer. Adicione-as ao array args na sua configuração (ou ao comando claude mcp add após --).

Modo Sem Interface Gráfica

O navegador é executado com interface gráfica por padrão para que você possa assistir o que está acontecendo. Para executar sem interface gráfica — útil para CI ou shells remotos — passe --headless:

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

Escolha um Navegador

Alterne mecanismos com a flag --browser. Os valores suportados são chrome, firefox, webkit e msedge:

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

Modos de Perfil

Playwright MCP suporta três modos de perfil:

• Persistente (padrão): O estado de login e cookies persistem entre sessões.
• Isolado: Passe --isolated para iniciar cada sessão do zero, opcionalmente alimentada com --storage-state.
• Extensão do navegador: Passe --extension para anexar às suas abas de navegador existentes através da extensão Playwright MCP Bridge.

Servidor HTTP Autônomo

Se você precisar executar um navegador com interface gráfica em algum lugar sem um display conectado (ou de um worker IDE), inicie o servidor separadamente e conecte via HTTP.

Abra um segundo terminal — deixe-o rodando pela sessão inteira — e inicie o servidor lá:

npx @playwright/mcp@latest --port 8931

Mantenha esse terminal aberto. É o que expõe o navegador em localhost:8931 para que você possa visualizar a sessão em seu próprio navegador e para que Claude Code tenha algo para se conectar. Fechar o terminal desliga o servidor.

Então, no terminal onde você executa Claude Code, aponte para o endpoint atualizando sua configuração:

{
  "mcpServers": {
    "playwright": {
      "url": "http://localhost:8931/mcp"
    }
  }
}

Fluxos de Trabalho Práticos que Vale a Pena Roubar

Depois que Playwright MCP está conectado, Claude Code pode lidar com scaffolding de testes end-to-end, reproduções de bugs, verificações de simulação de API, auditorias de página e testes de fumaça de lançamento — qualquer coisa que envolva dirigir um navegador e relatar de volta.

Duas coisas tornam esses prompts realmente funcionarem na prática. Primeiro, um CLAUDE.md na raiz do seu projeto que documenta sua URL de staging, credenciais de demonstração e qualquer convenção que o agente deva seguir — sem ele, “faça login como o usuário de demonstração” não tem nada para se ancorar. Segundo, se você quer que Claude Code puxe contexto de issues ou tickets, conecte um segundo servidor MCP para isso — o servidor GitHub MCP é a escolha comum. Pule ambos e Claude Code (razoavelmente) perguntará o que é a issue #482.

Por Que Parear Claude Code com Playwright MCP?

Algumas razões pelas quais essa combinação é difícil de vencer:

• Nativa do terminal: Tudo acontece onde você já trabalha. Sem troca de contexto para um executor de testes separado.
• Primeiro acessibilidade: Snapshots vencem capturas de tela em velocidade e confiabilidade, e funcionam sem um modelo de visão.
• Playwright real por baixo: Qualquer coisa que você possa fazer com Playwright em código, você pode fazer aqui — multi-navegador, simulação de rede, estado de armazenamento e muito mais.
• Composável com outros servidores MCP: Empilhe Playwright ao lado do GitHub, seu banco de dados ou seu servidor MCP de monitoramento e Claude Code pode mover trabalho end-to-end em todos eles.
• Padrão aberto: MCP é portável. O mesmo servidor Playwright funciona em Cursor, VS Code, Windsurf e Claude Desktop se você mudar de cliente.

Adicione o servidor, execute /mcp para confirmar, e seu próximo prompt “vá testar a página de login” se torna uma sessão de navegador real — orientada por Claude Code, assistida (ou não) em modo com interface gráfica, e verificável através de snapshots de acessibilidade.