Selenium MCP

Servidor Selenium MCP para agentes de IA — 39 ferramentas de automação de navegador com snapshots de página, dicas de seletores, múltiplas sessões e execução em lote.

GitHubExperimente este MCPPatrocinado

Documentação

selenium-mcp

Servidor Selenium MCP para agentes de IA — 41 ferramentas para automação de navegador real: navegação, cliques, digitação, asserções, capturas de tela, gerenciamento de múltiplas sessões, snapshots de página com referências estáveis de elementos, dicas persistentes de seletores e execução em lote de múltiplas etapas.

Construído com TypeScript, o SDK oficial do MCP e o Selenium WebDriver — validação rigorosa de entrada com zod, esperas explícitas e respostas estruturadas projetadas para agentes de LLM.

Instalação com um clique

Novidades na versão 0.3.0

Novas ferramentas: select_option para menus suspensos, scroll (incluindo páginas com rolagem infinita e painéis roláveis), history para voltar, avançar e atualizar, e wait_for_page para aguardar uma URL ou título após um redirecionamento.
Testes responsivos: window agora pode redimensionar a viewport para um tamanho exato, como um celular de 390x844, ou maximizá-la.
Melhor escolha de ferramentas pelos agentes de IA: cada ferramenta e parâmetro agora explica o que faz, o que retorna e quando usar uma ferramenta semelhante em vez dela.
Alteração significativa: open_url e wait_until_visible foram removidos por serem duplicados. Use navigate e wait_for_element com visible: true.
Versões verificadas: cada versão é testada de ponta a ponta contra um navegador real e publicada com proveniência do npm.

Consulte o changelog para obter detalhes.

Configuração

Claude Code

claude mcp add selenium -- npx -y @gaforov/selenium-mcp@latest

Claude Desktop / Cursor / Windsurf / outros clientes MCP

Adicione à configuração MCP do seu cliente (por exemplo, claude_desktop_config.json ou .cursor/mcp.json):

{
  "mcpServers": {
    "selenium": {
      "command": "npx",
      "args": ["-y", "@gaforov/selenium-mcp@latest"]
    }
  }
}

VS Code

code --add-mcp '{"name":"selenium","command":"npx","args":["-y","@gaforov/selenium-mcp@latest"]}'

Goose

goose session --with-extension "npx -y @gaforov/selenium-mcp@latest"

IntelliJ IDEA / IDEs JetBrains

Configurações → Ferramentas → Assistente de IA → Model Context Protocol → Adicionar, com o comando npx e os argumentos -y @gaforov/selenium-mcp@latest. Guia completo em docs/CLIENT_INTEGRATION.md.

A partir do código-fonte

git clone https://github.com/gaforov/selenium-mcp.git
cd selenium-mcp
npm install
npm run build

Em seguida, aponte seu cliente MCP para node /absolute/path/to/selenium-mcp/dist/server.js.

Exemplo de uso

Pergunte ao seu agente de IA:

Use o selenium-mcp para abrir o Chrome, ir para https://example.com,, ler o título da página, tirar uma captura de tela e fechar o navegador.

O agente encadeia start_browser → navigate → get_title → take_screenshot → stop_browser por conta própria — sem necessidade de scripts.

Requisitos

Node.js 20+
Chrome, Firefox ou Edge instalados (o Selenium Manager provisiona o driver correspondente automaticamente)

Comparação

A maioria dos servidores Selenium MCP envolve os comandos básicos do WebDriver. Este adiciona a camada que torna os agentes confiáveis:

Recurso	selenium-mcp	Servidores Selenium MCP típicos
Snapshot de página com referências estáveis de elementos (`capture_page`)	✅	raro
Memória persistente de seletores por domínio (`selector_hint_*`)	✅	❌
Navegação paralela em múltiplas sessões	✅	raro
Execução em lote de múltiplas etapas em uma única chamada	✅	❌
Asserções de teste integradas	✅	alguns
Rastreamento de chamadas de ferramentas (log de auditoria NDJSON)	✅	❌
Validação rigorosa de entrada + erros estruturados	✅	varia
Cada ferramenta e parâmetro descritos para agentes de IA (garantido por testes)	✅	varia
Testes de ponta a ponta contra um navegador real no CI	✅	alguns

Por que selenium-mcp

Fluxos de trabalho baseados em snapshot — capture_page retorna um snapshot da página com referências estáveis de elementos que o agente pode usar diretamente, sem adivinhação frágil de seletores
Dicas de seletores — persiste localizadores funcionais por domínio para que automações repetidas fiquem mais rápidas e confiáveis ao longo do tempo
Execução em lote — batch_execute executa sequências restritas de múltiplas etapas em uma única chamada de ferramenta, reduzindo idas e voltas
Múltiplas sessões — criar, selecionar, listar e destruir sessões de navegador em paralelo
Erros amigáveis para agentes — cada resposta é estruturada e validada com zod, para que os agentes possam se recuperar em vez de travar
Rastreamento opcional — rastreamento NDJSON de cada chamada de ferramenta para depuração e auditoria

Ferramentas (41)

Categoria	Ferramentas
Ciclo de vida do navegador	`start_browser`, `stop_browser`, `session_create`, `session_select`, `session_list`, `session_destroy`
Navegação	`navigate`, `history` (voltar/avançar/atualizar), `wait_for_page` (URL/título), `get_current_url`, `get_title`
Descoberta de elementos	`find_element`, `wait_for_element`, `capture_page`, `get_page_source`
Interação	`click`, `retry_click`, `interact` (passar o mouse/clique duplo/clique direito), `type`, `select_option`, `scroll`, `press_key`, `upload_file`
Leitura	`get_text`, `get_attribute`
Asserções	`assert_text`, `assert_visible`, `assert_attribute`
Scripts	`execute_script`, `batch_execute`
Dicas de seletores	`selector_hint_save`, `selector_hint_get`, `selector_hint_list`, `selector_hint_delete`
Janelas e contexto	`window` (abas, janelas, redimensionar/maximizar), `frame`, `alert`
Cookies	`add_cookie`, `get_cookies`, `delete_cookie`
Captura	`take_screenshot`

Documentação completa de parâmetros: docs/TOOL_REFERENCE.md

Recursos MCP

browser-status://current — status ao vivo do navegador/sessão
accessibility://current — snapshot de acessibilidade da página atual

Rastreamento opcional

Ative o rastreamento leve em NDJSON de todas as chamadas de ferramentas:

SELENIUM_MCP_TRACE=true
SELENIUM_MCP_TRACE_PATH=./logs/selenium-mcp-trace.ndjson

Se SELENIUM_MCP_TRACE_PATH for omitido, o padrão é logs/selenium-mcp-trace.ndjson.

Documentação

Contribuindo

Contribuições são bem-vindas — relatórios de bugs, solicitações de recursos e pull requests. Consulte CONTRIBUTING.md para começar.

npm run typecheck
npm run build
npm test

Licença

MIT. Consulte LICENSE.