MCP-Browser

MCP server que permite a qualquer agente de IA controlar um navegador real usando Playwright.

Funcionalidades

• Controle total de navegador via IA
• 17 tools prontas para uso
• Reuso automático de abas (mesmo domínio)
• Preenchimento automático de formulários
• Fluxos agentísticos com retry
• Compatível com qualquer plataforma MCP

Pré-requisitos

Dependência	Versão mínima
Node.js	18+
npm	9+

Instalação

# 1. Clonar o repositório
git clone https://git.jf.eng.br/jfeng/MCP-Browser.git
cd MCP-Browser

# 2. Instalar dependências
npm install

# 3. Instalar Chromium do Playwright
npx playwright install chromium

# Linux: instalar dependências do sistema
sudo npx playwright install-deps chromium

Configuração por plataforma

Todas as plataformas usam o mesmo padrão:

Comando:   node
Argumento: /caminho/absoluto/MCP-Browser/server.js
Transport: stdio

OpenCode

opencode mcp add

• Nome: meu-navegador
• Tipo: Local
• Comando: node /caminho/MCP-Browser/server.js

Cursor

~/.cursor/mcp.json (global) ou .cursor/mcp.json (projeto):

{
  "mcpServers": {
    "browser": {
      "command": "node",
      "args": ["/caminho/MCP-Browser/server.js"]
    }
  }
}

Claude Desktop

%APPDATA%\Claude\claude_desktop_config.json (Windows) ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)

{
  "mcpServers": {
    "browser": {
      "command": "node",
      "args": ["/caminho/MCP-Browser/server.js"]
    }
  }
}

Windsurf

~/.windsurf/mcp.json:

{
  "mcpServers": {
    "browser": {
      "command": "node",
      "args": ["/caminho/MCP-Browser/server.js"]
    }
  }
}

Trae

Settings → Extensions → MCP → Adicionar server:

• Name: browser
• Command: node
• Args: ["/caminho/MCP-Browser/server.js"]

Antigravity

Configuração de MCP → Novo server:

• Name: browser
• Type: stdio
• Command: node /caminho/MCP-Browser/server.js

VS Code

.vscode/mcp.json:

{
  "mcpServers": {
    "browser": {
      "command": "node",
      "args": ["/caminho/MCP-Browser/server.js"]
    }
  }
}

Qualquer plataforma MCP

Se suporta MCP stdio transport, use:

Comando:   node
Argumento: /caminho/absoluto/MCP-Browser/server.js

Tools disponíveis (17)

#	Tool	Descrição	Parâmetros
1	open_url	Abre uma URL	url
2	click	Clica por seletor CSS	selector
3	type	Digita texto em campo	selector, text
4	screenshot	Captura screenshot	fullPage (opcional)
5	get_text	Extrai texto da página	selector (opcional)
6	get_links	Lista links	selector (opcional)
7	wait_for_selector	Espera elemento aparecer	selector, timeout
8	extract_elements	Extrai elementos com atributos	selector, attributes
9	smart_click	Clica por texto visível	text
10	smart_type	Digita por label/placeholder	label, text
11	get_buttons	Lista botões disponíveis	—
12	smart_wait_navigation	Espera mudança de URL	timeout (opcional)
13	get_forms	Lista formulários e campos	—
14	fill_form_auto	Preenche formulário auto	data
15	agent_flow	Fluxo automático simples	goal, data
16	agent_flow_v2	Fluxo com retry/fallback	goal, data, retries
17	close_browser	Fecha o navegador	—

Exemplos de uso

Abrir site e extrair conteúdo

open_url("https://example.com")
get_text()
get_links()
screenshot()

Login automático

open_url("https://site.com/login")
fill_form_auto({"email": "user@test.com", "password": "1234"})
smart_click("Entrar")
smart_wait_navigation()

Scraping com atributos

open_url("https://site.com/produtos")
extract_elements(".produto", ["href", "data-id"])

Estrutura do projeto

MCP-Browser/
├── server.js              # Servidor MCP (entry point)
├── browser.js             # Engine Playwright (singleton)
├── package.json
├── docs.html              # Documentação detalhada
└── tools/
    ├── openUrl.js
    ├── click.js
    ├── type.js
    ├── screenshot.js
    ├── getText.js
    ├── getLinks.js
    ├── getButtons.js
    ├── getForms.js
    ├── extractElements.js
    ├── waitForSelector.js
    ├── smartClick.js
    ├── smartType.js
    ├── fillFormAuto.js
    ├── smartWaitNavigation.js
    ├── agentFlow.js
    ├── agentFlowV2.js
    └── closeBrowser.js

Comportamento

• Reuso de abas: mesmo domínio reutiliza aba, domínios diferentes abrem nova aba
• Headed mode: navegador abre visível. Para headless, edite browser.js e mude headless: true
• Singleton: uma única instância do navegador compartilhada entre todas as tools

Solução de problemas

Problema	Solução
Tools não aparecem	Reiniciar a IDE após configurar MCP
node: not found	Instalar Node.js 18+ e adicionar ao PATH
Chromium não encontrado	npx playwright install chromium
Erro de permissão (Linux)	sudo npx playwright install-deps chromium
Caminho com espaços	Usar aspas no caminho

Caminhos por SO

Sistema	Exemplo
Windows	C:/Users/seuuser/mcp-browser/server.js
macOS	/Users/seuuser/mcp-browser/server.js
Linux	/home/seuuser/mcp-browser/server.js

Importante: Nunca usar \ simples. Sempre / ou \\.

Licença

MIT