browser-mcp

Servidor MCP local de automação de navegador para o Claude Code: dá ao Claude ferramentas para navegar, clicar, digitar e inspecionar páginas web reais usando o Google Chrome já instalado na máquina.

Por que existe

A maioria das libs de automação simula clique/digitação via eventos de mouse/teclado no nível do sistema operacional (CDP). Isso funciona bem em apps modernos, mas quebra silenciosamente em várias aplicações web legadas (ex: JSF/PrimeFaces), onde o listener de evento é delegado via jQuery e não recebe o evento simulado. Este servidor dispara os eventos DOM (mousedown/mouseup/click, input/change) diretamente no elemento via JavaScript, o que se mostrou mais confiável nesses casos.

Também inclui um browser_snapshot: uma árvore de texto compacta da página (em vez de screenshot), pensada pra gastar poucos tokens quando não é preciso conferir visualmente.

Requisitos

• Node.js (testado com v16)
• Google Chrome instalado na máquina (usa o binário do sistema, não baixa um Chromium embutido)

Instalação

git clone <url-do-repo>
cd browser-mcp
npm install

Configuração

Variável	Padrão	Descrição
BROWSER_MCP_CHROME_PATH	/usr/bin/google-chrome-stable	Caminho do binário do Chrome
BROWSER_MCP_DOWNLOAD_DIR	./downloads	Pasta onde downloads feitos pelo navegador são salvos

Registrar no Claude Code

claude mcp add browser -- node /caminho/completo/para/browser-mcp/server.js

Ferramentas disponíveis

Ferramenta	Descrição
browser_navigate	Abre uma URL (lança o Chrome na primeira chamada)
browser_click	Clica em um elemento via seletor CSS
browser_type	Preenche um campo de texto
browser_select	Seleciona uma opção em um <select>
browser_wait_for_selector	Espera um elemento aparecer (útil após AJAX)
browser_get_text	Lê o texto visível de um elemento ou da página
browser_snapshot	Árvore de texto compacta dos elementos relevantes da página
browser_upload_file	Faz upload de um arquivo em um <input type="file">
browser_screenshot	Tira um screenshot (viewport, página inteira ou de um elemento)
browser_evaluate	Executa JavaScript arbitrário na página
browser_close	Encerra a sessão do navegador

Arquitetura

Um único arquivo (server.js), sem dependências além de puppeteer-core. Fala o protocolo MCP via JSON-RPC 2.0 sobre stdio (uma mensagem por linha). As chamadas de ferramenta são serializadas em fila: automação de navegador é sequencial por natureza, então duas chamadas concorrentes contra a mesma aba/página são executadas uma após a outra, nunca em paralelo.

Licença

MIT — veja LICENSE.