Playwright MCP Server

Um servidor MCP que utiliza Playwright para automação de navegador e web scraping.

GitHub
5.7k
Experimente este MCPPatrocinado

Documentação

MseeP.ai Security Assessment Badge
MseeP.ai Security Assessment

Playwright MCP Server 🎭

Trust Score smithery badge

Um servidor Model Context Protocol que fornece capacidades de automação de navegador usando Playwright. Este servidor permite que LLMs interajam com páginas da web, tirem capturas de tela, gerem código de teste, façam scraping de páginas e executem JavaScript em um ambiente de navegador real.

mcp-playwright MCP server

✨ Novidades na v1.0.10

🎯 Emulação de Dispositivos com 143 Presets de Dispositivos Reais!

Teste suas aplicações web em perfis de dispositivos reais com um simples comando:

// Test on iPhone 13 with automatic user-agent, touch support, and device pixel ratio
await playwright_resize({ device: "iPhone 13" });

// Switch to iPad with landscape orientation
await playwright_resize({ device: "iPad Pro 11", orientation: "landscape" });

// Test desktop view
await playwright_resize({ device: "Desktop Chrome" });

Suporte a Linguagem Natural para Assistentes de IA:

  • "Testar no iPhone 13"
  • "Mudar para visualização iPad"
  • "Rotacionar para paisagem"

Suporta 143 dispositivos: iPhone, iPad, Pixel, Galaxy e navegadores Desktop com emulação adequada de viewport, user-agent, eventos de toque e proporções de pixels do dispositivo.

📚 Ver Referência Rápida de Dispositivos | Guia de Prompts

Captura de Tela

Playwright + Claude

Documentação | Referência da API

Instalação

Você pode instalar o pacote usando npm, mcp-get ou Smithery:

Usando npm:

npm install -g @executeautomation/playwright-mcp-server

Usando mcp-get:

npx @michaellatman/mcp-get@latest install @executeautomation/playwright-mcp-server

Usando Smithery

Para instalar o Playwright MCP para Claude Desktop automaticamente via Smithery:

npx @smithery/cli install @executeautomation/playwright-mcp-server --client claude

Usando Claude Code:

claude mcp add --transport stdio playwright npx @executeautomation/playwright-mcp-server

Instalação no VS Code

Instale o servidor Playwright MCP no VS Code usando um destes botões:

Install in VS Code Install in VS Code Insiders

Alternativamente, você pode instalar o servidor Playwright MCP usando o CLI do VS Code:

# For VS Code
code --add-mcp '{"name":"playwright","command":"npx","args":["@executeautomation/playwright-mcp-server"]}'

# For VS Code Insiders
code-insiders --add-mcp '{"name":"playwright","command":"npx","args":["@executeautomation/playwright-mcp-server"]}'

Após a instalação, o servidor Playwright MCP do ExecuteAutomation estará disponível para uso com seu agente GitHub Copilot no VS Code.

Instalação do Navegador

Instalação Automática (Recomendada)

O Playwright MCP Server instala automaticamente os binários do navegador quando você o usa pela primeira vez. Quando o servidor detecta que um navegador está ausente, ele irá:

  1. Baixar e instalar automaticamente o navegador necessário (Chromium, Firefox ou WebKit)
  2. Exibir o progresso da instalação no console
  3. Repetir sua solicitação assim que a instalação for concluída

Nenhuma configuração manual necessária! Basta começar a usar o servidor, e ele cuida da instalação do navegador para você.

Instalação Manual (Opcional)

Se você preferir instalar navegadores manualmente ou encontrar problemas com a instalação automática:

# Install all browsers
npx playwright install

# Or install specific browsers
npx playwright install chromium
npx playwright install firefox
npx playwright install webkit

Local de Armazenamento do Navegador

Os navegadores são instalados em:

  • Windows: %USERPROFILE%\AppData\Local\ms-playwright
  • macOS: ~/Library/Caches/ms-playwright
  • Linux: ~/.cache/ms-playwright

Configuração para usar o Playwright Server

Modo Padrão (stdio)

Este é o modo recomendado para Claude Desktop.

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@executeautomation/playwright-mcp-server"]
    }
  }
}

Nota: No modo stdio, o registro de logs é automaticamente direcionado apenas para arquivos (não console) para manter uma comunicação JSON-RPC limpa. Os logs são gravados em ~/playwright-mcp-server.log.

Modo HTTP (Servidor Autônomo)

Ao executar navegador com interface gráfica em sistemas sem display ou em processos de trabalho de IDEs, você pode executar o servidor MCP como um servidor HTTP autônomo:

Nota para usuários do Claude Desktop: O Claude Desktop atualmente requer o modo stdio (configuração de comando/argumentos). O modo HTTP é recomendado para VS Code, clientes personalizados e implantações remotas. Consulte CLAUDE_DESKTOP_CONFIG.md para detalhes.

Iniciando o Servidor HTTP

# Using npx
npx @executeautomation/playwright-mcp-server --port 8931

# Or after global installation
playwright-mcp-server --port 8931

O servidor iniciará e exibirá os endpoints disponíveis:

==============================================
Playwright MCP Server (HTTP Mode)
==============================================
Port: 8931

ENDPOINTS:
- SSE Stream:     GET  http://localhost:8931/sse
- Messages:       POST http://localhost:8931/messages?sessionId=<id>
- MCP (unified):  GET  http://localhost:8931/mcp
- MCP (unified):  POST http://localhost:8931/mcp?sessionId=<id>
- Health Check:   GET  http://localhost:8931/health
==============================================

Configuração do Cliente para Modo HTTP

⚠️ CRÍTICO: O campo "type": "http" é OBRIGATÓRIO para transporte HTTP/SSE!

Para VS Code GitHub Copilot:

{
  "github.copilot.chat.mcp.servers": {
    "playwright": {
      "url": "http://localhost:8931/mcp",
      "type": "http"
    }
  }
}

Para Clientes MCP Personalizados:

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

Importante: Sem "type": "http", a conexão falhará.

Para Claude Desktop: Use o modo stdio em vez disso (veja Modo Padrão acima)

Casos de Uso para Modo HTTP

  • Executar navegadores com interface gráfica em sistemas sem display (ex.: servidores remotos)
  • Integrar com VS Code GitHub Copilot
  • Executar o servidor como um serviço em segundo plano
  • Acessar o servidor de múltiplos clientes
  • Depuração com o endpoint /health
  • Integrações com clientes MCP personalizados

Monitoramento: O servidor inclui um sistema de monitoramento que inicia em uma porta alocada dinamicamente (evitando conflitos). Verifique a saída do console para a porta real.

Nota: Para Claude Desktop, continue usando o modo stdio (Modo Padrão acima) por enquanto.

Solução de Problemas

Erro "No transport found for sessionId"

Sintoma: Erro 400 com mensagem "Bad Request: No transport found for sessionId"

Solução:

  1. Verifique se a configuração inclui "type": "http"

    {
  "url": "http://localhost:8931/mcp",
  "type": "http"  // ← This is REQUIRED!
}

  2. Verifique se os logs do servidor mostram a conexão:

    # Should see these in order:
# 1. "Incoming request" - GET /mcp
# 2. "Transport registered" - with sessionId
# 3. "POST message received" - with same sessionId

  3. Reinicie tanto o servidor quanto o cliente

Problemas de Conexão

  • Servidor não iniciando: Verifique se a porta 8931 está disponível
  • Acesso externo bloqueado: Isso é por design (segurança). O servidor vincula-se apenas ao localhost
  • Para acesso remoto: Use túnel SSH: 
    ssh -L 8931:localhost:8931 user@remote-server

Testes

Este projeto usa Jest para testes. Os testes estão localizados no diretório src/__tests__.

Executando Testes

Você pode executar os testes usando um dos seguintes comandos:

# Run tests using the custom script (with coverage)
node run-tests.cjs

# Run tests using npm scripts
npm test           # Run tests without coverage
npm run test:coverage  # Run tests with coverage
npm run test:custom    # Run tests with custom script (same as node run-tests.cjs)

O relatório de cobertura de testes será gerado no diretório coverage.

Executando evals

O pacote de evals carrega um cliente mcp que então executa o arquivo index.ts, então não há necessidade de recompilar entre testes. Você pode carregar variáveis de ambiente prefixando o comando npx. Documentação completa pode ser encontrada aqui.

OPENAI_API_KEY=your-key  npx mcp-eval src/evals/evals.ts src/tools/codegen/index.ts

Contribuindo

Ao adicionar novas ferramentas, por favor, esteja atento ao comprimento do nome da ferramenta. Alguns clientes, como Cursor, têm um limite de 60 caracteres para o nome combinado de servidor e ferramenta (server_name:tool_name).

Nosso nome de servidor é playwright-mcp. Por favor, garanta que seus nomes de ferramentas sejam curtos o suficiente para não exceder este limite.

Histórico de Estrelas

Star History Chart