Agent Browser MCP

mcp-server-agent-browser

Status: Beta — O wrapper de CLI é coberto por testes unitários e um teste de fumaça stdio com navegador falso. A restauração de cookies em uma reinicialização real do Chromium ainda é uma verificação manual.

Permita que LLMs controlem um navegador real. Este servidor MCP envolve agent-browser (Vercel Labs) para que qualquer cliente MCP possa navegar, preencher formulários, clicar, capturar a árvore de acessibilidade e tirar screenshots.

Não é o web_search / open_page do Grok. Esses buscam documentos. Este executa Chromium. Use busca para encontrar uma URL e depois browser_navigate.

Pré-requisitos

cargo install agent-browser
agent-browser install

Chame browser_doctor se algo estiver faltando.

Build

cargo build --release

Binário: target/release/mcp-server-agent-browser

cargo test
./tests/test-stdio.sh

A restauração de login real do Chromium não está no CI. Após um login com janela, reinicie o processo MCP e confirme que o próximo browser_navigate ainda está logado.

Configuração

Cliente MCP (stdio):

{
  "mcpServers": {
    "agent-browser": {
      "command": "/path/to/mcp-server-agent-browser"
    }
  }
}

TOML opcional em ~/.config/mcp-server-agent-browser/config.toml (veja config.example.toml). Arquivo ausente usa padrões. Substitua o caminho com MCP_AGENT_BROWSER_CONFIG.

Configuração	Padrão	Significado
headed	false	Mostrar uma janela. Somente no momento do lançamento; browser_close primeiro se um daemon headless já estiver ativo. Também AGENT_BROWSER_HEADED=1.
persist	true	--restore simples por session_id (chave de sessão padrão default) mais --namespace mcp-server.
keep_daemon	false	Se falso, a saída do MCP executa close para que o estado de restauração seja salvo e o Chrome não vaze.
namespace	mcp-server	Isola os sockets do daemon e os arquivos de restauração deste MCP de um humano usando a CLI.
command_timeout_secs	120	Timeout do wrapper. O timeout de ação de 25s do Playwright é deixado intacto (IPC da CLI é ~30s).
idle_timeout	1h	Desligamento ocioso do daemon. Use "0" com keep_daemon = true.
download_dir	~/Downloads	--download-path. ~ é expandido.
profile	não definido	Diretório opcional persistente de dados do usuário do Chrome. Não é seu perfil diário do Chrome.
encryption_key_file	não definido	Define AGENT_BROWSER_ENCRYPTION_KEY. Arquivos de restauração são credenciais; texto puro a menos que isso seja definido.
AGENT_BROWSER_PATH	agent-browser	Binário da CLI.

allowed_domains é opcional. Localhost é permitido a menos que você defina uma lista que o exclua.

O que ele pode fazer

Mesmo conjunto de interações de antes (navegar, clicar, digitar, capturar, screenshot, cookies, eval, CDP, sessões), além de:

• browser_doctor — CLI, config, persistir, headed/DISPLAY, adivinhação de daemon. Não inicia o Chrome.
• browser_get_text pattern — regex sobre o texto da página com duas linhas de contexto.
• browser_wait — load / url / text além de um seletor.

Loop típico:

1. browser_navigate
2. browser_snapshot (-i para interativo)
3. browser_click / browser_fill com @refs
4. browser_screenshot se você precisar de pixels

Persistência

Com persist = true (padrão), cada sessão salva cookies e localStorage ao fechar e no intervalo de autosave da CLI. O estado fica em ~/.agent-browser/, com namespace mcp-server. session_ids isolados não compartilham uma chave de restauração.

Faça login com janela uma vez, browser_close ou saia do MCP, inicie novamente. A próxima navegação deve restaurar essa sessão.

Um processo MCP morto pode deixar o daemon em execução. browser_doctor relata isso. O desligamento ocioso ainda salva se persistir estiver ativo.

Limitações

• Chromium via agent-browser (Playwright). Sem busca.
• Headed é ignorado até que o daemon existente seja fechado.
• Snap Chromium no Ubuntu pode falhar ao anunciar sua porta DevTools; prefira o navegador do agent-browser install ou executable_path.
• Gravações (screenshot, pdf, download) devem ser relativas, sob /tmp ou sob download_dir.
• O timeout de ação de 25s do Playwright é um limite da CLI upstream, não deste wrapper.

Licença

MIT