MCP Browser Bridge

Ponte entre Model Context Protocol (MCP) e automação de navegador. 37 ferramentas. 3 modos de operação. Chrome real ou headless.

✨ Funcionalidades

• 37 ferramentas MCP registradas em src/browser_mcp/tools.py via @app.tool(...) e expostas pelo servidor MCP em src/browser_mcp/server.py:18 e src/browser_mcp/server.py:24.

• 3 modos de operação: Playwright/headless por padrão (src/browser_mcp/browser_manager.py:126), CDP para Chrome existente (src/browser_mcp/browser_manager.py:211) e Chrome Extension via WebSocket (src/browser_mcp/browser_manager.py:252).

• Network monitoring com captura de request/response, filtros e exportação HAR no Playwright (src/browser_mcp/network.py:11, src/browser_mcp/network.py:178) e no modo extensão (src/browser_mcp/extension_bridge.py:196, src/browser_mcp/extension_bridge.py:360).

• Indicadores visuais por injeção JavaScript em 5 componentes/fases documentáveis no código: overlay, highlight, status, ripple e segurança por cor (src/browser_mcp/visual_indicator.py:8, src/browser_mcp/visual_indicator.py:69, src/browser_mcp/visual_indicator.py:86, src/browser_mcp/visual_indicator.py:113, src/browser_mcp/browser_manager.py:1097).

• Captura de erros e warnings de console no modo extensão (extension/injected.js:96, extension/background.js:703, src/browser_mcp/tools.py:1129).

• Agente autônomo com loop OBSERVE -> THINK -> CHECK -> ACT -> RECORD (src/browser_mcp/agent.py:107) exposto pela ferramenta browser_agent_task (src/browser_mcp/tools.py:990).

• Accessibility tree com refs @e1, @e2, etc. geradas pelo BrowserManager (src/browser_mcp/browser_manager.py:312) e usadas por clique, digitação e hover (src/browser_mcp/tools.py:271, src/browser_mcp/tools.py:317, src/browser_mcp/tools.py:407).

• Suporte multi-provedor de LLM: DeepSeek, OpenAI, Anthropic, Ollama e endpoints customizados via LLM_BASE_URL (src/browser_mcp/llm_client.py:18, src/browser_mcp/llm_client.py:25, src/browser_mcp/llm_client.py:34, src/browser_mcp/llm_client.py:48).

• Stealth mode ativado por padrão com launch args, user-agent realista, navigator.webdriver removido e CSP bypass no contexto Playwright (src/browser_mcp/browser_manager.py:40, src/browser_mcp/browser_manager.py:49, src/browser_mcp/browser_manager.py:136, src/browser_mcp/browser_manager.py:151).

• Integração Hermes Agent por launcher dedicado que limpa variáveis conflitantes e executa browser_mcp.server no .venv (hermes-mcp.sh:5, hermes-mcp.sh:9, hermes-mcp.sh:14).

Related MCP server: Chrome MCP Server

📦 Instalação

O pacote é definido em pyproject.toml: Python >=3.11, dependências mcp, playwright, httpx, python-dotenv e websockets, extras de desenvolvimento e script browser-mcp-server (pyproject.toml:5, pyproject.toml:39, pyproject.toml:47, pyproject.toml:61).

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
playwright install chromium

Execução direta:

python -m browser_mcp.server
# ou, após instalar o pacote:
browser-mcp-server

Variáveis úteis:

🚀 Uso

1. Playwright, modo padrão

O servidor inicializa BrowserManager, LLMClient e o WebSocket server opcional antes de abrir o stdio MCP (src/browser_mcp/server.py:68, src/browser_mcp/server.py:77). Em uma chamada MCP:

{
  "name": "browser_navigate",
  "arguments": { "url": "https://example.com" }
}

{
  "name": "browser_screenshot",
  "arguments": { "path": "./example.png", "full_page": true }
}

2. CDP, Chrome existente

Inicie o Chrome com remote debugging e conecte a ferramenta MCP:

/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
  --remote-debugging-port=9222 \
  --user-data-dir=/tmp/mcp-chrome-cdp

{
  "name": "browser_connect_to_existing",
  "arguments": { "cdp_url": "http://localhost:9222" }
}

Esse modo usa chromium.connect_over_cdp(...), aproveita contextos/páginas já existentes quando disponíveis e passa a marcar _mode = "cdp" (src/browser_mcp/browser_manager.py:226, src/browser_mcp/browser_manager.py:228, src/browser_mcp/browser_manager.py:245).

3. Chrome Extension, navegador real do usuário

1. Instale a extensão em chrome://extensions carregando a pasta extension/.

2. Inicie o WebSocket standalone ou o servidor MCP:

python websocket_server_standalone.py
# ou
python manage_mcp_browser.py start

3. Configure na extensão o token de ~/.mcp_browser_token e conecte:

{
  "name": "browser_connect_to_extension",
  "arguments": { "ws_url": "ws://localhost:8765" }
}

O modo extensão usa a sessão real do Chrome via ExtensionBridge, fecha Playwright se necessário e alterna _mode = "extension" (src/browser_mcp/browser_manager.py:258, src/browser_mcp/browser_manager.py:278, src/browser_mcp/browser_manager.py:280).

🛠️ Ferramentas

Os nomes abaixo são os nomes reais registrados em src/browser_mcp/tools.py. A contagem verificada é 37.

Observações verificáveis:

• Não há ferramenta MCP pública chamada browser_scroll; a extensão tem helper interno scroll em src/browser_mcp/extension_bridge.py:162, mas ele não é registrado em tools.py.

• browser_get_visible_text e browser_get_interactive_elements existem como métodos auxiliares do BrowserManager (src/browser_mcp/browser_manager.py:980, src/browser_mcp/browser_manager.py:1009), mas não como ferramentas MCP públicas.

• browser_get_console_errors requer modo extensão, porque chama extension_get_console_errors (src/browser_mcp/browser_manager.py:1067).

🔌 Integração com Hermes Agent

Use o launcher do projeto:

./hermes-mcp.sh

Ele entra no diretório do projeto, limpa PYTHONPATH, PYTHONSTARTUP e VIRTUAL_ENV, e executa .venv/bin/python -s -m browser_mcp.server (hermes-mcp.sh:5, hermes-mcp.sh:9, hermes-mcp.sh:14). Isso evita misturar pacotes do ambiente Hermes com o Python do .venv.

Para usar no Hermes Agent, configure o engine de browser para MCP no lado do Hermes (browser.engine=mcp) e aponte o comando do MCP server para hermes-mcp.sh. Este repositório fornece o servidor e o launcher; a leitura de browser.engine=mcp é responsabilidade do Hermes, não deste pacote.

🏗️ Arquitetura

Fluxo principal:

MCP Client
  -> MCP Server stdio (src/browser_mcp/server.py)
    -> ToolRegistry (src/browser_mcp/tools.py)
      -> BrowserManager
        -> Playwright Chromium
        -> Chrome via CDP
        -> ExtensionBridge -> WebSocketServer -> Chrome Extension MV3 -> Chrome real

O servidor MCP usa mcp.server.Server, registra handlers list_tools e call_tool, inicia componentes opcionais e roda via stdio (src/browser_mcp/server.py:15, src/browser_mcp/server.py:18, src/browser_mcp/server.py:24, src/browser_mcp/server.py:77).

O WebSocket server escuta em localhost:8765, usa implementação built-in em asyncio por padrão, implementa handshake/frame WebSocket compatível com RFC 6455, valida Origin, exige token e encaminha comandos/respostas entre servidor e extensão (src/browser_mcp/websocket_server.py:71, src/browser_mcp/websocket_server.py:97, src/browser_mcp/websocket_server.py:174, src/browser_mcp/websocket_server.py:180, src/browser_mcp/websocket_server.py:202, src/browser_mcp/websocket_server.py:228, src/browser_mcp/websocket_server.py:516).

A extensão Chrome é Manifest V3, usa service worker, content script em <all_urls>, permissões activeTab, tabs, storage, scripting, alarms e debugger, e expõe injected.js como recurso acessível (extension/manifest.json:4, extension/manifest.json:6, extension/manifest.json:17, extension/manifest.json:20, extension/manifest.json:42).

O switch de comandos da extensão tem 21 comandos no código atual, não 20: navigate, new_tab, click, type, screenshot, get_content, execute_javascript, get_dom_snapshot, press_key, get_url, get_title, go_back, go_forward, reload, get_visible_text, get_interactive_elements, get_attributes, wait, list_tabs, activate_tab, manage_session (extension/background.js:200 a extension/background.js:572).

🔐 Segurança

• Token auth no WebSocket: token em ~/.mcp_browser_token, criado com secrets.token_urlsafe(32) e permissões 0600 (src/browser_mcp/websocket_server.py:48, src/browser_mcp/websocket_server.py:51, src/browser_mcp/websocket_server.py:61, src/browser_mcp/websocket_server.py:63).

• Validação de Origin: conexões com Origin diferente de chrome-extension://... recebem 403 Forbidden (src/browser_mcp/websocket_server.py:202).

• Formas de autenticação aceitas: bearer token, subprotocolo mcp-token.* ou query string ?token=... (src/browser_mcp/websocket_server.py:210, src/browser_mcp/websocket_server.py:215, src/browser_mcp/websocket_server.py:221).

• Comparação constante: token validado com hmac.compare_digest(...) (src/browser_mcp/websocket_server.py:228).

• Limite de payload: frames maiores que 64 MiB são rejeitados (src/browser_mcp/websocket_server.py:46, src/browser_mcp/websocket_server.py:331).

• CSP bypass no modo extensão: execute_javascript tenta chrome.scripting.executeScript; se CSP bloquear eval, usa chrome.debugger com Runtime.evaluate (extension/background.js:300, extension/background.js:321, extension/background.js:635).

📊 Métricas

Estado verificado neste checkout:

• 37 ferramentas MCP em src/browser_mcp/tools.py.

• 43 testes coletáveis em tests/ com env -u PYTHONPATH -u PYTHONSTARTUP -u VIRTUAL_ENV .venv/bin/pytest --collect-only -q.

• mypy configurado em pyproject.toml com disallow_untyped_defs = true, mas a execução atual de env -u PYTHONPATH -u PYTHONSTARTUP -u VIRTUAL_ENV .venv/bin/mypy src reporta 43 erros. Portanto, não é correto afirmar “mypy strict: 0 errors” neste estado.

• ruff configurado em pyproject.toml, mas env -u PYTHONPATH -u PYTHONSTARTUP -u VIRTUAL_ENV .venv/bin/ruff check src tests reporta 12 erros. Portanto, não é correto afirmar “ruff: 0 errors” neste estado.

• Metadados de pacote presentes para wheel/sdist via Hatchling e script browser-mcp-server (pyproject.toml:1, pyproject.toml:61, pyproject.toml:64, pyproject.toml:67).

📄 Licença

MIT (LICENSE).