Playwright MCP

Automação de navegador usando Playwright, permitindo que LLMs interajam com páginas da web por meio de snapshots estruturados de acessibilidade.

GitHubExperimente este MCPPatrocinado

Documentação

Playwright MCP

Um servidor Model Context Protocol (MCP) que fornece capacidades de automação de navegador usando Playwright. Este servidor permite que LLMs interajam com páginas web por meio de snapshots estruturados de acessibilidade, dispensando a necessidade de screenshots ou modelos ajustados visualmente.

Principais Recursos

Rápido e leve: Usa a árvore de acessibilidade do Playwright, não entrada baseada em pixels.
Amigável para LLMs: Não requer modelos de visão, opera puramente em dados estruturados.
Aplicação determinística de ferramentas: Evita ambiguidades comuns em abordagens baseadas em screenshots.

Casos de Uso

Navegação web e preenchimento de formulários
Extração de dados de conteúdo estruturado
Testes automatizados conduzidos por LLMs
Interação geral com navegador para agentes

Exemplo de configuração

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

Instalação no VS Code

Você pode instalar o servidor Playwright MCP usando a CLI do VS Code:

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

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

Linha de comando

O servidor Playwright MCP suporta as seguintes opções de linha de comando:

--browser <browser>: Navegador ou canal do Chrome a ser usado. Valores possíveis:
- chrome, firefox, webkit, msedge
- Canais do Chrome: chrome-beta, chrome-canary, chrome-dev
- Canais do Edge: msedge-beta, msedge-canary, msedge-dev
- Padrão: chrome
--caps <caps>: Lista separada por vírgulas de capacidades a serem habilitadas, valores possíveis: tabs, pdf, history, wait, files, install. O padrão é todos.
--cdp-endpoint <endpoint>: Endpoint CDP para conectar
--executable-path <path>: Caminho para o executável do navegador
--headless: Executar navegador em modo headless (com interface por padrão)
--device: Emular dispositivo móvel
--user-data-dir <path>: Caminho para o diretório de dados do usuário
--port <port>: Porta para escutar no transporte SSE
--host <host>: Host para vincular o servidor. O padrão é localhost. Use 0.0.0.0 para vincular a todas as interfaces.
--allowed-origins <origins>: Lista separada por ponto e vírgula de origens permitidas para o navegador solicitar. O padrão é permitir todas. Origens que correspondem tanto a --allowed-origins quanto a --blocked-origins serão bloqueadas.
--blocked-origins <origins>: Lista separada por ponto e vírgula de origens bloqueadas para o navegador solicitar. Origens que correspondem tanto a --allowed-origins quanto a --blocked-origins serão bloqueadas.
--vision: Executar servidor que usa screenshots (snapshots Aria são usados por padrão)
--output-dir: Diretório para arquivos de saída
--config <path>: Caminho para o arquivo de configuração

Perfil de usuário

O Playwright MCP iniciará o navegador com o novo perfil, localizado em

- `%USERPROFILE%\AppData\Local\ms-playwright\mcp-{channel}-profile` on Windows
- `~/Library/Caches/ms-playwright/mcp-{channel}-profile` on macOS
- `~/.cache/ms-playwright/mcp-{channel}-profile` on Linux

Todas as informações de login serão armazenadas nesse perfil. Você pode excluí-lo entre sessões se quiser limpar o estado offline.

Arquivo de configuração

O servidor Playwright MCP pode ser configurado usando um arquivo de configuração JSON. Aqui está o formato completo de configuração:

{
  // Browser configuration
  browser?: {
    // Browser type to use (chromium, firefox, or webkit)
    browserName?: 'chromium' | 'firefox' | 'webkit';

    // Path to user data directory for browser profile persistence
    userDataDir?: string;

    // Browser launch options (see Playwright docs)
    // @see https://playwright.dev/docs/api/class-browsertype#browser-type-launch
    launchOptions?: {
      channel?: string;        // Browser channel (e.g. 'chrome')
      headless?: boolean;      // Run in headless mode
      executablePath?: string; // Path to browser executable
      // ... other Playwright launch options
    };

    // Browser context options
    // @see https://playwright.dev/docs/api/class-browser#browser-new-context
    contextOptions?: {
      viewport?: { width: number, height: number };
      // ... other Playwright context options
    };

    // CDP endpoint for connecting to existing browser
    cdpEndpoint?: string;

    // Remote Playwright server endpoint
    remoteEndpoint?: string;
  },

  // Server configuration
  server?: {
    port?: number;  // Port to listen on
    host?: string;  // Host to bind to (default: localhost)
  },

  // List of enabled capabilities
  capabilities?: Array<
    'core' |    // Core browser automation
    'tabs' |    // Tab management
    'pdf' |     // PDF generation
    'history' | // Browser history
    'wait' |    // Wait utilities
    'files' |   // File handling
    'install' | // Browser installation
    'testing'   // Testing
  >;

  // Enable vision mode (screenshots instead of accessibility snapshots)
  vision?: boolean;

  // Directory for output files
  outputDir?: string;

  // Network configuration
  network?: {
    // List of origins to allow the browser to request. Default is to allow all. Origins matching both `allowedOrigins` and `blockedOrigins` will be blocked.
    allowedOrigins?: string[];

    // List of origins to block the browser to request. Origins matching both `allowedOrigins` and `blockedOrigins` will be blocked.
    blockedOrigins?: string[];
  };
 
  /**
   * Do not send image responses to the client.
   */
  noImageResponses?: boolean;
}

Você pode especificar o arquivo de configuração usando a opção de linha de comando --config:

npx @hyhfish/mcp-hyh@latest --config path/to/config.json

Executando no Linux

Ao executar navegador com interface em sistema sem display ou a partir de processos de trabalho dos IDEs, execute o servidor MCP a partir do ambiente com o DISPLAY e passe o sinalizador --port para habilitar o transporte SSE.

npx @hyhfish/mcp-hyh@latest --port 8931

E então, na configuração do cliente MCP, defina o url para o endpoint SSE:

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

Docker

NOTA: A implementação Docker suporta apenas chromium headless no momento.

{
  "mcpServers": {
    "playwright": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "--init", "--pull=always", "mcr.microsoft.com/playwright/mcp"]
    }
  }
}

Você pode construir a imagem Docker você mesmo.

docker build -t mcr.microsoft.com/playwright/mcp .

Uso programático

import http from 'http';

import { createServer } from '@hyhfish/mcp-hyh';
import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';

http.createServer(async (req, res) => {
  // ...

  // Creates a headless Playwright MCP server with SSE transport
  const connection = await createConnection({ browser: { launchOptions: { headless: true } } });
  const transport = new SSEServerTransport('/messages', res);
  await connection.connect(transport);

  // ...
});

Modos de ferramentas

As ferramentas estão disponíveis em dois modos:

Modo Snapshot (padrão): Usa snapshots de acessibilidade para melhor desempenho e confiabilidade
Modo Visão: Usa screenshots para interações baseadas em visual

Para usar o Modo Visão, adicione o sinalizador --vision ao iniciar o servidor:

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

O Modo Visão funciona melhor com modelos de uso de computador que são capazes de interagir com elementos usando espaço de coordenadas X Y, com base no screenshot fornecido.

Interações baseadas em Snapshot

browser_snapshot
- Título: Snapshot da página
- Descrição: Captura snapshot de acessibilidade da página atual, isso é melhor que screenshot
- Parâmetros: Nenhum
- Somente leitura: true

browser_click
- Título: Clicar
- Descrição: Realizar clique em uma página web
- Parâmetros:
  - element (string): Descrição legível do elemento usada para obter permissão para interagir com o elemento
  - ref (string): Referência exata do elemento alvo do snapshot da página
- Somente leitura: false

browser_drag
- Título: Arrastar mouse
- Descrição: Realizar arrastar e soltar entre dois elementos
- Parâmetros:
  - startElement (string): Descrição legível do elemento de origem usada para obter permissão para interagir com o elemento
  - startRef (string): Referência exata do elemento de origem do snapshot da página
  - endElement (string): Descrição legível do elemento de destino usada para obter permissão para interagir com o elemento
  - endRef (string): Referência exata do elemento de destino do snapshot da página
- Somente leitura: false

browser_hover
- Título: Passar o mouse
- Descrição: Passar o mouse sobre elemento na página
- Parâmetros:
  - element (string): Descrição legível do elemento usada para obter permissão para interagir com o elemento
  - ref (string): Referência exata do elemento alvo do snapshot da página
- Somente leitura: true

browser_type
- Título: Digitar texto
- Descrição: Digitar texto em elemento editável
- Parâmetros:
  - element (string): Descrição legível do elemento usada para obter permissão para interagir com o elemento
  - ref (string): Referência exata do elemento alvo do snapshot da página
  - text (string): Texto para digitar no elemento
  - submit (boolean, opcional): Se deve enviar o texto digitado (pressionar Enter depois)
  - slowly (boolean, opcional): Se deve digitar um caractere por vez. Útil para acionar manipuladores de teclado na página. Por padrão, todo o texto é preenchido de uma vez.
- Somente leitura: false

browser_select_option
- Título: Selecionar opção
- Descrição: Selecionar uma opção em um menu suspenso
- Parâmetros:
  - element (string): Descrição legível do elemento usada para obter permissão para interagir com o elemento
  - ref (string): Referência exata do elemento alvo do snapshot da página
  - values (array): Matriz de valores para selecionar no menu suspenso. Pode ser um único valor ou múltiplos valores.
- Somente leitura: false

browser_take_screenshot
- Título: Tirar um screenshot
- Descrição: Tirar um screenshot da página atual. Você não pode realizar ações com base no screenshot, use browser_snapshot para ações.
- Parâmetros:
  - raw (boolean, opcional): Se deve retornar sem compressão (em formato PNG). O padrão é false, que retorna uma imagem JPEG.
  - filename (string, opcional): Nome do arquivo para salvar o screenshot. O padrão é page-{timestamp}.{png|jpeg} se não especificado.
  - element (string, opcional): Descrição legível do elemento usada para obter permissão para capturar o elemento. Se não for fornecida, o screenshot será tirado da viewport. Se o elemento for fornecido, a ref também deve ser fornecida.
  - ref (string, opcional): Referência exata do elemento alvo do snapshot da página. Se não for fornecida, o screenshot será tirado da viewport. Se a ref for fornecida, o elemento também deve ser fornecido.
- Somente leitura: true

Interações baseadas em Visão

browser_screen_capture
- Título: Tirar um screenshot
- Descrição: Tirar um screenshot da página atual
- Parâmetros: Nenhum
- Somente leitura: true

browser_screen_move_mouse
- Título: Mover mouse
- Descrição: Mover o mouse para uma posição dada
- Parâmetros:
  - element (string): Descrição legível do elemento usada para obter permissão para interagir com o elemento
  - x (number): Coordenada X
  - y (number): Coordenada Y
- Somente leitura: true

browser_screen_click
- Título: Clicar
- Descrição: Clicar com o botão esquerdo do mouse
- Parâmetros:
  - element (string): Descrição legível do elemento usada para obter permissão para interagir com o elemento
  - x (number): Coordenada X
  - y (number): Coordenada Y
- Somente leitura: false

browser_screen_drag
- Título: Arrastar mouse
- Descrição: Arrastar com o botão esquerdo do mouse
- Parâmetros:
  - element (string): Descrição legível do elemento usada para obter permissão para interagir com o elemento
  - startX (number): Coordenada X inicial
  - startY (number): Coordenada Y inicial
  - endX (number): Coordenada X final
  - endY (number): Coordenada Y final
- Somente leitura: false

browser_screen_type
- Título: Digitar texto
- Descrição: Digitar texto
- Parâmetros:
  - text (string): Texto para digitar no elemento
  - submit (boolean, opcional): Se deve enviar o texto digitado (pressionar Enter depois)
- Somente leitura: false

Gerenciamento de Abas

browser_tab_list
- Título: Listar abas
- Descrição: Listar abas do navegador
- Parâmetros: Nenhum
- Somente leitura: true

browser_tab_new
- Título: Abrir uma nova aba
- Descrição: Abrir uma nova aba
- Parâmetros:
  - url (string, opcional): A URL para navegar na nova aba. Se não for fornecida, a nova aba ficará em branco.
- Somente leitura: true

browser_tab_select
- Título: Selecionar uma aba
- Descrição: Selecionar uma aba por índice
- Parâmetros:
  - index (number): O índice da aba a ser selecionada
- Somente leitura: true

browser_tab_close
- Título: Fechar uma aba
- Descrição: Fechar uma aba
- Parâmetros:
  - index (number, opcional): O índice da aba a ser fechada. Fecha a aba atual se não for fornecido.
- Somente leitura: false

Navegação

browser_navigate
- Título: Navegar para uma URL
- Descrição: Navegar para uma URL
- Parâmetros:
  - url (string): A URL para navegar
  - userDataDir (string, opcional): Diretório de dados do usuário personalizado para o perfil do navegador
- Somente leitura: false

功能增强: O parâmetro userDataDir do comando browser_navigate é um recurso aprimorado em relação ao projeto original Playwright MCP da Microsoft. Este parâmetro permite alternar dinamicamente o diretório do perfil do usuário do navegador durante a navegação, sem precisar reiniciar todo o serviço. Quando este parâmetro é especificado, o navegador atual é fechado e reiniciado usando o novo diretório de dados do usuário.

browser_navigate_back
- Título: Voltar
- Descrição: Voltar para a página anterior
- Parâmetros: Nenhum
- Somente leitura: true

browser_navigate_forward
- Título: Avançar
- Descrição: Avançar para a próxima página
- Parâmetros: Nenhum
- Somente leitura: true

Teclado

browser_press_key
- Título: Pressionar uma tecla
- Descrição: Pressionar uma tecla no teclado
- Parâmetros:
  - key (string): Nome da tecla a ser pressionada ou um caractere a ser gerado, como ArrowLeft ou a
- Somente leitura: false

Console

browser_console_messages
- Título: Obter mensagens do console
- Descrição: Retorna todas as mensagens do console
- Parâmetros: Nenhum
- Somente leitura: true

Arquivos e Mídia

browser_file_upload
- Título: Enviar arquivos
- Descrição: Envia um ou vários arquivos
- Parâmetros:
  - paths (array): Os caminhos absolutos dos arquivos a serem enviados. Pode ser um único arquivo ou vários arquivos.
- Somente leitura: false

browser_pdf_save
- Título: Salvar como PDF
- Descrição: Salva a página como PDF
- Parâmetros:
  - filename (string, opcional): Nome do arquivo para salvar o PDF. O padrão é page-{timestamp}.pdf se não for especificado.
- Somente leitura: true

Utilitários

browser_close
- Título: Fechar navegador
- Descrição: Fecha a página
- Parâmetros: Nenhum
- Somente leitura: true

browser_wait_for
- Título: Aguardar
- Descrição: Aguarda o texto aparecer ou desaparecer ou um tempo especificado passar
- Parâmetros:
  - time (number, opcional): O tempo de espera em segundos
  - text (string, opcional): O texto a aguardar
  - textGone (string, opcional): O texto a aguardar para desaparecer
- Somente leitura: true

browser_resize
- Título: Redimensionar janela do navegador
- Descrição: Redimensiona a janela do navegador
- Parâmetros:
  - width (number): Largura da janela do navegador
  - height (number): Altura da janela do navegador
- Somente leitura: true

browser_install
- Título: Instalar o navegador especificado na configuração
- Descrição: Instala o navegador especificado na configuração. Chame isso se você receber um erro sobre o navegador não estar instalado.
- Parâmetros: Nenhum
- Somente leitura: false

browser_handle_dialog
- Título: Lidar com um diálogo
- Descrição: Lida com um diálogo
- Parâmetros:
  - accept (boolean): Se deve aceitar o diálogo.
  - promptText (string, opcional): O texto do prompt no caso de um diálogo de prompt.
- Somente leitura: false

browser_network_requests
- Título: Listar solicitações de rede
- Descrição: Retorna todas as solicitações de rede desde o carregamento da página
- Parâmetros: Nenhum
- Somente leitura: true

Testes

browser_generate_playwright_test
- Título: Gerar um teste Playwright
- Descrição: Gera um teste Playwright para o cenário fornecido
- Parâmetros:
  - name (string): O nome do teste
  - description (string): A descrição do teste
  - steps (array): As etapas do teste
- Somente leitura: true