Guia prático de Playwright MCP: faça Claude, Codex e Cursor controlarem o navegador

Você adiciona [mcp_servers.playwright] ao .codex/config.toml, executa codex e o navegador realmente abre. Mesmo assim, a IA não chama as ferramentas de navegador; ou abre a página, mas não encontra o botão na barra de navegação. Este guia traz a configuração completa para Claude Code, Codex e Cursor, a checklist da primeira validação e as permissões de navegador que você não deve entregar para a IA sem pensar.

---

O que é Playwright MCP

Playwright MCP é o MCP server mantido oficialmente pela Microsoft que expõe a automação de navegador do Playwright para ferramentas de programação com IA por meio do Model Context Protocol. O mecanismo central não é reconhecimento de captura de tela. Ele opera sobre a accessibility tree, oferecendo à IA uma visão estruturada da página para encontrar botões, links, campos de entrada e outros elementos interativos.

Recursos principais e lista de ferramentas

Playwright MCP cobre os principais cenários de automação de navegador:

• Navegação: abrir URL, avançar, voltar, recarregar
• Clique e entrada: clicar em elementos, preencher formulários, usar o teclado
• Capturas e snapshots: tirar capturas de tela e obter accessibility snapshots
• Diálogos e abas: lidar com alert/confirm/prompt e gerenciar múltiplas abas
• Rede e console: interceptar requisições de rede e capturar console logs
• Estado de armazenamento: salvar e restaurar cookies, localStorage e sessionStorage

Com isso, ele consegue lidar tanto com um clique simples quanto com fluxos complexos de envio de formulário.

Diferença em relação a Playwright CLI/SKILLS

O README oficial da Microsoft deixa clara a troca entre duas rotas:

• Rota MCP: adequada quando você precisa de estado persistente, introspecção rica e contexto contínuo de navegador, como em automação exploratória, testes auto-reparáveis ou tarefas longas. O custo é que tool schema e accessibility tree entram no contexto e consomem tokens.
• Rota CLI + SKILLS: adequada para fluxos de código de alto rendimento, com menor consumo de contexto, mas exige chamar Playwright por comandos ou scripts.

Se você já usa uma ferramenta de programação com IA compatível com MCP, como Claude Code, Codex ou Cursor, Playwright MCP é a forma mais direta de levar ferramentas de navegador para esse fluxo.

Diferença em relação ao Browser Use

Browser Use é um agent loop em Python. Você escreve código Python contra a API dele, e o agent decide as ações de navegador a partir de um prompt. Playwright MCP é diferente: ele não fornece o agent loop. Ele fornece a camada de ferramentas de navegador, e seu MCP client existente, como Claude Code, Codex ou Cursor, decide quando chamar essas ferramentas.

Se você é desenvolvedor Python e quer começar rápido com Browser Agent, primeiro leia o tutorial de Browser Use para abrir páginas, clicar em botões e extrair informações. Se você já trabalha dentro de um MCP client e quer conectar navegador à ferramenta atual, este guia ajuda a instalar, validar e proteger o Playwright MCP.

Não é substituto de um framework de testes

Playwright MCP não substitui o framework de testes do Playwright. Ele é útil para automação exploratória e validação frontend, mas uma suíte E2E estável ainda deve ser escrita com scripts de teste Playwright. Testes precisam de determinismo, repetibilidade e manutenção; ações de navegador guiadas por IA não são totalmente controláveis. Se você se interessa por testes em modo navegador, veja também Vitest Browser Mode.

---

Configurar Playwright MCP no Claude Code

Pré-requisitos

Claude Code precisa de Node.js 18+ para executar Playwright MCP. Confira sua versão do Node:

node --version

Se for menor que 18, atualize o Node.js primeiro.

Comando para adicionar

Claude Code oferece um comando específico para gerenciar MCP. Execute na raiz do projeto:

claude mcp add playwright npx @playwright/mcp@latest

Esse comando registra o Playwright MCP server no Claude Code. Use @playwright/mcp@latest; não copie nomes antigos de pacotes comunitários como @executeautomation/playwright-mcp-server.

Configuração de projeto .mcp.json

Se quiser compartilhar a configuração do Playwright MCP com a equipe, crie um .mcp.json na raiz do projeto:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"],
      "env": {
        "BROWSER_PATH": "/usr/bin/chromium"
      }
    }
  }
}

Quando Claude Code encontra um .mcp.json de projeto, ele pede aprovação. Isso evita que um projeto introduza silenciosamente um MCP server não confiável.

Expansão de variáveis de ambiente

.mcp.json suporta expansão de variáveis de ambiente para caminhos específicos da máquina e valores sensíveis:

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

Tool Search e gerenciamento de tokens de saída

Claude Code ativa MCP Tool Search por padrão. Isso carrega ferramentas sob demanda e reduz o uso de contexto. Quando a saída MCP é grande, Claude Code também gerencia tokens, com limite padrão de 25.000 tokens. Se a IA não usar ferramentas de navegador, verifique:

1. Se o MCP server iniciou corretamente nos logs do Claude Code
2. Se Tool Search está ativado, o que é padrão no Claude Code
3. Se o Node.js está na versão 18 ou superior

---

Configurar Playwright MCP no Codex

OpenAI Codex suporta MCP servers tanto na CLI quanto na IDE extension, mas a configuração é diferente da do Claude Code.

Comando para adicionar

A CLI do Codex fornece um comando de gerenciamento MCP:

codex mcp add playwright -- npx @playwright/mcp@latest

No Codex, -- separa o nome do server do comando real.

Local do arquivo de configuração

A configuração MCP do Codex fica em config.toml. Há dois locais:

• Nível de usuário: ~/.codex/config.toml, com efeito global
• Nível de projeto: .codex/config.toml na raiz do projeto, apenas para esse projeto

A CLI e a IDE extension compartilham essa configuração.

Trecho de config.toml

Para configurar manualmente, adicione isto ao config.toml:

[mcp_servers.playwright]
command = "npx"
args = ["@playwright/mcp@latest"]

Se precisar passar variáveis de ambiente ou ajustar aprovação de ferramentas, acrescente:

env_vars = ["HOME", "STORAGE_STATE_PATH"]
approval_mode = "prompt"

Modos de aprovação de ferramentas

Codex oferece três modos de aprovação:

• approval_mode = "allow": executa automaticamente todas as chamadas de ferramenta
• approval_mode = "prompt": pede confirmação do usuário antes de cada chamada
• approval_mode = "deny": nega todas as chamadas de ferramenta

Para ferramentas de alto risco do Playwright MCP, como browser_run_code_unsafe, use:

[mcp_servers.playwright]
command = "npx"
args = ["@playwright/mcp@latest"]
disabled_tools = ["browser_run_code_unsafe"]
approval_mode = "prompt"

Assim, ferramentas de alto risco não rodam automaticamente e ações sensíveis ficam atrás de aprovação humana.

Suporte a HTTP server

Codex suporta dois tipos de MCP server:

• STDIO server: comunicação com processo local, útil para ferramentas que precisam acessar o sistema local, como Playwright MCP
• HTTP server: suporta bearer token e autenticação OAuth

Playwright MCP usa STDIO, então a configuração HTTP não é necessária no fluxo padrão.

---

Configurar Playwright MCP no Cursor

Cursor configura MCP pela Settings UI, diferente dos caminhos de linha de comando do Claude Code e do Codex.

Passos na UI

Segundo a documentação oficial do Playwright, a configuração no Cursor é:

1. Abra Cursor Settings (Cmd+, ou pelo menu Settings)
2. Vá para a página MCP (Settings -> MCP)
3. Clique em “Add new MCP Server”
4. Preencha a configuração:
   • Server name: playwright
   • Command type: npx
   • Command: @playwright/mcp@latest

Configuração de parâmetros padrão

A configuração MCP server do Cursor aceita os parâmetros padrão do Playwright MCP:

• --headless: modo sem janela visível; em desenvolvimento, headed é mais fácil de observar
• --browser: escolher navegador (chrome/firefox/webkit/msedge)
• --output-dir: caminho do diretório de saída
• --storage-state: caminho do arquivo de estado de login

A lista completa aparece abaixo na tabela de parâmetros padrão.

Referência de configuração

A documentação MCP do Cursor está na documentação oficial do Cursor. Para detalhes de Playwright MCP, use a documentação oficial do Playwright e o README da Microsoft como referência, e garanta que o pacote oficial seja @playwright/mcp@latest.

---

Tabela de parâmetros de configuração padrão

Playwright MCP oferece vários parâmetros para controlar comportamento do navegador, limites de segurança e gerenciamento de saída.

Parâmetro	Função	Padrão	Observação de segurança
--headless	Modo sem mostrar janela do navegador	false (headed)	Em desenvolvimento, use headed para observar as ações do navegador
--browser	Escolher tipo de navegador	chrome	Opções: chrome, firefox, webkit, msedge
--allowed-origins	Lista de origens permitidas	Sem limite	Não é um limite de segurança; não afeta redirects e não protege sites sensíveis sozinho
--blocked-origins	Lista de origens bloqueadas	Nenhuma	Não é um limite de segurança, mesma ressalva
--isolated	Modo isolado, cada sessão usa profile próprio	false	Recomendado para clients concorrentes ou vários projetos
--storage-state	Caminho de arquivo de estado de login	Nenhum	Salva cookies e localStorage; cuidado com contas reais
--output-dir	Diretório de saída para capturas, logs etc.	Nenhum	Defina um caminho para encontrar resultados com facilidade
--save-session	Salvar estado da sessão	false	Use junto com persistent profile
--snapshot-mode	Modo de accessibility snapshot	default	Controla o nível de detalhe do snapshot
--allow-unrestricted-file-access	Permitir acesso irrestrito a arquivos	false	Alto risco; ative com cuidado
--secrets	Configuração de secrets por variáveis de ambiente ou arquivos	Nenhum	Usado para gerenciar informações sensíveis

Lembrete importante: a documentação oficial afirma que --allowed-origins e --blocked-origins não são limites de segurança e não afetam redirects. Se precisar restringir sites acessíveis pela IA, não dependa só desses parâmetros.

---

Comparativo dos três modos de profile

Playwright MCP suporta três modos de profile, que afetam persistência de login, concorrência e limites de segurança.

Modo	Persistência de login	Caminho do profile	Concorrência	Quando usar	Recomendação de segurança
persistent	Salva cookies, localStorage etc.	macOS: ~/Library/Caches/ms-playwright/mcp-{channel}-{workspace-hash}	Um profile só pode ser usado por uma browser instance por vez	Tarefas longas em que a IA precisa lembrar login	Não use conta real por padrão; comece com conta de teste
isolated	Não salva; cada sessão é independente	Diretório temporário, limpo a cada sessão	Suporta clients concorrentes ou vários projetos	Testes, exploração, tarefas sem login	Recomendado como padrão em produção
browser extension	Salva dependendo do navegador	Diretório da extensão do navegador	Depende do navegador	Conectar a uma sessão de navegador existente	Uso avançado; entenda o modelo de segurança de extensões

Limite do persistent profile

Um persistent profile só pode ser usado por uma browser instance por vez. Se você precisa de vários clients ou projetos usando Playwright MCP ao mesmo tempo, precisa:

• Usar o modo --isolated
• Ou configurar um --user-data-dir diferente para cada client

Exemplo de caminho persistent profile no macOS:

~/Library/Caches/ms-playwright/mcp-chrome-a1b2c3d4

A parte {workspace-hash} é gerada automaticamente pelo projeto, então projetos diferentes usam profiles diferentes.

Estado de login e limites de segurança

persistent profile salva cookies, localStorage e sessionStorage. A IA pode acessar o estado de login salvo no navegador. Se você usa uma conta real, ela pode acessar dados pessoais, informações de pagamento e configurações da conta.

Práticas recomendadas:

• Em produção, use --isolated para não salvar estado de login
• Quando a IA precisar operar logada, use uma conta de teste em vez de uma conta real
• Não deixe a IA fazer login automaticamente na sua conta real nem visitar páginas de pagamento

A gestão de estado de login fica para um artigo posterior sobre login state em navegadores de IA. Aqui, o objetivo é só marcar o limite.

---

Alerta de segurança sobre browser_run_code_unsafe

Alerta de segurança: browser_run_code_unsafe permite executar scripts Playwright arbitrários. A documentação oficial o marca como RCE-equivalent. Ative apenas para MCP clients totalmente confiáveis. Em produção, desative ou exija aprovação humana via approval_mode: prompt no Codex.

Playwright MCP inclui uma ferramenta de alto risco chamada browser_run_code_unsafe. Ela pode executar qualquer script Playwright no contexto do navegador. O perigo é direto:

• Se o MCP client for comprometido ou o comportamento da IA não estiver controlado, um invasor pode usar essa ferramenta para executar código arbitrário
• A IA pode ler todos os dados do navegador, incluindo cookies, localStorage, sessionStorage e dados pessoais de contas logadas
• Se o navegador estiver em uma página de pagamento ou configurações de conta, a IA pode ler e vazar dados sensíveis

Recomendações de configuração segura

Ambiente de produção:

1. Desative browser_run_code_unsafe:

   Adicione isto ao ~/.codex/config.toml do Codex:

   [mcp_servers.playwright]
   command = "npx"
   args = ["@playwright/mcp@latest"]
   disabled_tools = ["browser_run_code_unsafe"]

2. Ou defina modo de aprovação:

   [mcp_servers.playwright]
   command = "npx"
   args = ["@playwright/mcp@latest"]
   approval_mode = "prompt"

   Assim, o Codex mostra uma confirmação antes de cada chamada a browser_run_code_unsafe, e você precisa aprovar manualmente.

Ambiente de desenvolvimento:

Se você realmente precisa usar browser_run_code_unsafe:

• Ative apenas no desenvolvimento local, não em produção nem com contas reais
• Garanta que você entende totalmente o script que será executado
• Não deixe a IA gerar e executar scripts automaticamente; escreva você mesmo o script e peça para a IA executar esse script conhecido

Não recomendado para iniciantes

Se você está começando com Playwright MCP, não comece por browser_run_code_unsafe. Primeiro use ferramentas mais seguras do Playwright MCP, como browser_click, browser_navigate e browser_screenshot. Elas têm limites mais claros e não executam código arbitrário.

---

Checklist de segurança para MCP Tools

MCP permite que a IA chame ferramentas externas, mas “conectar MCP” não significa “deixar a IA fazer qualquer coisa automaticamente”. Você precisa controlar limites de segurança no lado do client e no lado do server.

Recomendações de segurança no lado do client

1. Pedir confirmação para ações sensíveis: antes de chamar browser_run_code_unsafe, visitar páginas de pagamento, alterar configurações de conta ou apagar dados, peça confirmação do usuário. Não deixe a IA executar essas operações de alto risco automaticamente.

2. Mostrar tool inputs antes da execução: deixe o usuário ver os parâmetros concretos que a IA vai usar. Por exemplo, se a IA for clicar em um botão, mostre o selector ou as coordenadas e confirme se estão corretos.

3. Evitar vazamento malicioso de dados: inspecione a saída das ferramentas para impedir que informações sensíveis, como senhas, tokens ou dados pessoais, sejam lidas pela IA e enviadas para fora. Se uma ferramenta retornar dados sensíveis, não deixe a IA gravar isso em logs nem enviar a serviços externos.

4. Definir timeout: operações de navegador podem travar, consumir recursos ou bloquear outras tarefas. Defina um timeout razoável para cada chamada, como 30 segundos, e cancele automaticamente ao exceder.

5. Registrar tool usage: mantenha logs de operação para auditoria e diagnóstico. Inclua nome da ferramenta, horário da chamada, parâmetros de entrada, resultado e registro de aprovação do usuário.

6. Verificar tool results: confira se capturas de tela, console logs e requisições de rede batem com o esperado. Se a IA disser “clique bem-sucedido”, mas a captura não mostrar mudança, investigue.

Recomendações de segurança no lado do server

Se você desenvolver seu próprio MCP server (Playwright MCP é o server oficial, você não precisa desenvolvê-lo), siga estas recomendações:

1. Validar entradas: valide URLs, seletores e textos de entrada para evitar ataques de injeção. Não deixe a IA passar uma URL maliciosa ou XSS payload sem validação.

2. Controlar acesso: limite domínios, caminhos de arquivo e capacidades de navegador acessíveis. Por exemplo, bloqueie IPs internos ou caminhos sensíveis.

3. Aplicar rate limit: evite que a IA chame ferramentas com tanta frequência que esgote recursos ou cause bloqueio no site alvo. Defina um limite razoável, como no máximo 10 chamadas por minuto.

4. Limpar saídas: remova informações sensíveis antes de retornar dados para a IA. Por exemplo, não retorne strings completas de cookies se apenas uma parte derivada for necessária.

---

Primeira tarefa de validação e checklist de aceite

Depois da configuração, use uma tarefa simples para verificar se o Playwright MCP está conectado corretamente.

Exemplo de tarefa

Peça para a IA abrir a preview local http://localhost:4321, clicar no menu de navegação, tirar uma captura e relatar console errors.

Passo a passo:

1. Confirme que Playwright MCP foi adicionado ao seu client, seja Claude Code, Codex ou Cursor

2. Inicie o servidor de desenvolvimento local, como Astro ou Next.js, e confirme que http://localhost:4321 está acessível

3. Digite este prompt no Claude Code/Codex/Cursor:

   Abra http://localhost:4321, clique em "Artigos" no menu de navegação, tire uma captura de tela e relate se a página tem console errors.

4. Observe se a IA chama ferramentas de navegador, se o navegador inicia e se a página abre

Checklist de aceite

Verificação	Resultado esperado	Como confirmar
O navegador inicia	Em headed mode, uma janela abre; em headless, o processo inicia	Observar UI ou gerenciador de processos
MCP server está conectado	Logs do client mostram “Connected to MCP server”	Verificar logs do client
accessibility snapshot retorna	A IA encontra o menu de navegação e clica	Saída da IA inclui descrição da ação de clique
Chamada de ferramenta exige aprovação	Depende da configuração; Codex pode mostrar diálogo de aprovação	Observar se o client pede confirmação
Saídas e logs são rastreáveis	Capturas, console logs e outras saídas aparecem em --output-dir	Verificar o diretório configurado

Diagnóstico de falhas

A IA não chama ferramentas de navegador:

• Confira se o MCP server foi adicionado corretamente nos logs do client
• Verifique se o client suporta MCP Tool Search; Claude Code ativa isso por padrão
• Confirme que Node.js está na versão 18 ou superior

O navegador abre, mas não encontra o botão:

• Playwright MCP opera na accessibility tree, não em capturas. Se a página não tiver rótulos semânticos ou atributos ARIA, a IA pode não reconhecer o elemento
• Verifique a estrutura HTML e confirme que o botão tem label acessível ou role
• Ou ajuste o parâmetro --snapshot-mode para mudar o nível de detalhe do snapshot

O navegador inicia e fecha imediatamente:

• Pode ser headless mode ou o script pode ter terminado
• Verifique os logs do client e confirme se o navegador iniciou e fechou normalmente
• Se você usa headed mode, a janela do navegador deve permanecer aberta até a IA relatar conclusão

---

Quando escolher Playwright MCP em vez de CLI/SKILLS

O README oficial da Microsoft afirma que, para coding agents em fluxos de código de alto rendimento, CLI + SKILLS pode ser mais adequado, porque MCP coloca tool schema e accessibility tree no contexto e consome tokens. MCP combina melhor com cenários que precisam de estado persistente, introspecção rica e contexto contínuo de navegador para automação exploratória, testes auto-reparáveis ou tarefas longas.

Tabela de comparação por cenário

Cenário	Recomendar Playwright MCP	Recomendar Playwright CLI + SKILLS
Automação exploratória, testes auto-reparáveis	Sim, adequado	Não, inadequado
Tarefas longas com contexto persistente de navegador	Sim, adequado	Não, inadequado
Fluxos de código de alto rendimento	Não, consome mais contexto	Sim, adequado
Necessidade de menor consumo possível de contexto	Não, inadequado	Sim, adequado
Você já usa um MCP client como Claude Code/Codex/Cursor	Sim, adequado	Não, inadequado

Este artigo não detalha o uso de SKILLS. Um artigo futuro vai cobrir validação de navegador com Codex na prática.

---

Resumo e próximos passos

Este guia cobriu a configuração de Playwright MCP no Claude Code, Codex e Cursor, a checklist da primeira validação e os limites de segurança: o risco RCE de browser_run_code_unsafe, a persistência de login nos modos de profile e o fato de --allowed-origins não ser um limite de segurança.

Resumo das diferenças de configuração

• Claude Code: use claude mcp add ou .mcp.json no nível do projeto; Tool Search vem ativado por padrão
• Codex: use codex mcp add ou config.toml; approval_mode controla ferramentas de alto risco
• Cursor: configure pela Settings UI, com um fluxo diferente dos outros dois

Próximos passos sugeridos

• Precisa comparar ferramentas: leia Browser Use vs Stagehand vs Playwright MCP, guia 2026 de seleção de ferramentas de navegador com IA
• Precisa gerenciar estado de login: leia Gerenciamento de estado de login em navegadores de IA
• Precisa de testes frontend: leia Testes e validação frontend com Playwright
• Precisa de validação de navegador com Codex: leia Validação de navegador com Codex na prática
• Precisa de infraestrutura gerenciada: leia Infraestrutura de navegadores gerenciados
• Precisa de segurança e aprovações: leia Segurança de navegadores de IA e design de aprovações

Se você acabou de configurar Playwright MCP, execute primeiro a tarefa de validação em localhost:4321. Confirme que o navegador inicia, que a IA chama ferramentas e que as capturas são gravadas no diretório configurado. Se algo falhar, siga a FAQ e verifique a versão do Node.js, os logs do client e o estado da conexão do MCP server.