MCP-Browser

MCP server que permite a qualquer agente de IA controlar um navegador real via Playwright. 17 tools Windows / Linux / macOS

Pré-requisitos

DependênciaVersão mínimaVerificar
Node.js18+node -v
npm9+npm -v
Playwright1.50+npx playwright --version

Instalação

1. Clonar ou copiar o projeto

# Opção A — git clone
git clone https://git.jf.eng.br/jfeng/MCP-Browser.git
cd MCP-Browser

# Opção B — copiar a pasta manualmente para qualquer diretório

2. Instalar dependências

npm install

3. Instalar navegadores do Playwright

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

4. Testar se funciona

node server.js

O servidor inicia e aguarda conexão via stdin/stdout (MCP stdio transport). Não aparece nada no terminal — isso é normal.

Estrutura do projeto

MCP-Browser/
├── server.js              ← servidor MCP (entry point)
├── browser.js             ← engine Playwright (singleton)
├── package.json
├── package-lock.json
├── docs.html              ← esta documentação
├── node_modules/
└── tools/
    ├── openUrl.js         ← abre URL (reusa aba se mesmo domínio)
    ├── click.js           ← clica por seletor CSS
    ├── type.js            ← digita texto em campo
    ├── screenshot.js      ← captura screenshot
    ├── getText.js         ← extrai texto da página
    ├── getLinks.js        ← lista todos os links
    ├── getButtons.js      ← lista botões disponíveis
    ├── getForms.js        ← lista formulários e campos
    ├── extractElements.js ← extrai elementos com atributos
    ├── waitForSelector.js ← espera elemento aparecer
    ├── smartClick.js      ← clica por texto visível
    ├── smartType.js       ← digita por label/placeholder
    ├── fillFormAuto.js    ← preenche formulário automaticamente
    ├── smartWaitNavigation.js ← espera navegação
    ├── agentFlow.js       ← fluxo automático simples
    ├── agentFlowV2.js     ← fluxo com retry e fallback
    └── closeBrowser.js    ← fecha o navegador

Configuração por plataforma

OpenCode

  1. Abra o terminal e execute:
    opencode mcp add
  2. Preencha os campos:
    • Nome: meu-navegador
    • Tipo: Local
    • Comando: node /caminho/absoluto/MCP-Browser/server.js
  3. Reinicie o OpenCode.
  4. Verifique: opencode mcp list

Cursor

  1. Abra Settings → MCP (ou .cursor/mcp.json no projeto).
  2. Adicione ao arquivo ~/.cursor/mcp.json (global) ou .cursor/mcp.json (projeto):
{
  "mcpServers": {
    "browser": {
      "command": "node",
      "args": ["/caminho/absoluto/MCP-Browser/server.js"]
    }
  }
}
  1. Reinicie o Cursor. As tools aparecerão no chat do Composer.

Claude Desktop

  1. Abra o arquivo de configuração:
    • Windows: %APPDATA%\Claude\claude_desktop_config.json
    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
    • Linux: ~/.config/Claude/claude_desktop_config.json
  2. Adicione:
{
  "mcpServers": {
    "browser": {
      "command": "node",
      "args": ["/caminho/absoluto/MCP-Browser/server.js"]
    }
  }
}
  1. Reinicie o Claude Desktop.

Windsurf (Codeium)

  1. Abra Settings → Cascade → MCP Servers.
  2. Ou edite ~/.windsurf/mcp.json:
{
  "mcpServers": {
    "browser": {
      "command": "node",
      "args": ["/caminho/absoluto/MCP-Browser/server.js"]
    }
  }
}
  1. Reinicie o Windsurf.

Trae

  1. Abra Settings → Extensions → MCP.
  2. Adicione server manualmente:
    • Name: browser
    • Command: node
    • Args: ["/caminho/absoluto/MCP-Browser/server.js"]
  3. Ou edite o arquivo de configuração do Trae equivalente ao mcp.json.

Antigravity

  1. Abra a configuração de MCP do Antigravity.
  2. Adicione um novo server com:
    • Name: browser
    • Type: stdio
    • Command: node /caminho/absoluto/MCP-Browser/server.js
  3. Salve e reinicie.

VS Code (com extensão MCP)

  1. Instale a extensão MCP no VS Code.
  2. Abra .vscode/mcp.json no workspace ou settings.json global.
  3. Adicione:
{
  "mcpServers": {
    "browser": {
      "command": "node",
      "args": ["/caminho/absoluto/MCP-Browser/server.js"]
    }
  }
}

Qualquer outra plataforma MCP

Se a plataforma suporta MCP stdio transport, use:

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

O servidor comunica via stdin/stdout — não precisa porta, não precisa daemon.

Caminhos por sistema operacional

SistemaFormato do caminhoExemplo
WindowsUse / ou \\C:/Users/seuuser/mcp-browser/server.js
macOSUnix path/Users/seuuser/mcp-browser/server.js
LinuxUnix path/home/seuuser/mcp-browser/server.js
Importante: Nunca use \ simples nos caminhos. Sempre / ou \\.

Lista de tools (17)

#ToolDescriçãoParâmetros
1open_urlAbre uma URL no navegadorurl (string, obrigatório)
2clickClica em elemento por seletor CSSselector (string, obrigatório)
3typeDigita texto em um camposelector, text
4screenshotCaptura screenshot da páginafullPage (bool, opcional)
5get_textExtrai texto da páginaselector (opcional, padrão: body)
6get_linksLista todos os linksselector (opcional, padrão: a)
7wait_for_selectorEspera elemento aparecer no DOMselector, timeout
8extract_elementsExtrai elementos com atributosselector, attributes (array)
9smart_clickClica pelo texto visíveltext (string, obrigatório)
10smart_typeDigita buscando por label/placeholderlabel, text
11get_buttonsLista botões disponíveis—
12smart_wait_navigationEspera mudança de URLtimeout (opcional)
13get_formsLista formulários e seus campos—
14fill_form_autoPreenche formulário automaticamentedata (objeto, obrigatório)
15agent_flowFluxo automático simplesgoal, data (opcional)
16agent_flow_v2Fluxo com retry e fallbackgoal, data, retries
17close_browserFecha 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()
get_text()

Scraping com atributos

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

Preencher formulário complexo

open_url("https://site.com/contato")
smart_type("nome", "João Silva")
type("#email", "joao@email.com")
smart_type("mensagem", "Olá, quero mais informações")
smart_click("Enviar")

Comportamento do navegador

Problemas comuns

ProblemaSolução
Tools não aparecem na plataforma Reiniciar a IDE/plataforma após configurar o MCP.
node: command not found Instalar Node.js 18+ e garantir que está no PATH.
Playwright não encontra Chromium npx playwright install chromium
Erro de permissão no Linux sudo npx playwright install-deps chromium
Página não carrega (conteúdo vazio) O servidor aguarda domcontentloaded + 1.5s. Se a página usa JS pesado, aumente o timeout em browser.js.
Erro ECONNREFUSED O servidor MCP usa stdio (stdin/stdout), não HTTP. Verifique se o comando está correto.
Caminho com espaços no Windows Use aspas: "C:/Users/Meu Usuario/mcp/server.js"

Licença

MIT — uso livre.