Skip to main content
Glama

browser-ai

Dê ao seu agente de IA um navegador de verdade pra operar.

browser-ai é um servidor MCP (stdio, biblioteca padrão pura — zero dependências) que deixa um agente de IA (Codex, Claude Code, Cursor…) controlar o Chrome: ler a página, clicar, digitar, navegar e tirar screenshot. Ele fala CDP (Chrome DevTools Protocol) direto com o navegador — então não instala extensão nenhuma: você sobe o Chrome com a porta de depuração e o agente assume a aba.

Como funciona

Agente (Codex)  ──MCP/stdio──►  web-ai  ──CDP──►  Chrome (porta 9222)  ──►  a aba

Related MCP server: @nimbus21.ai/chrome-devtools-mcp

Passo 1 — subir o Chrome com a porta de debug

Use um perfil dedicado (mantém a automação longe do seu perfil do dia a dia):

google-chrome --remote-debugging-port=9222 \
  --user-data-dir="$HOME/.browser-ai-profile"

(Qualquer navegador Chromium serve: chromium, brave, edge. Para rodar sem janela, acrescente --headless=new.)

Passo 2 — conferir a conexão

cd browser-ai
python3 -m webai doctor     # ✓ Chrome reachable ... N tab(s) open
python3 -m webai tabs       # lista as abas abertas

Passo 3 — plugar no Codex

No ~/.codex/config.toml:

[mcp_servers.browser-ai]
command = "python3"
args = ["-m", "webai", "mcp"]
# rode o Codex a partir da pasta browser-ai, OU instale com `pip install -e .`
# e use:  command = "web-ai"   args = ["mcp"]

Depois de pip install -e . o comando web-ai fica no PATH e dá para apontar de qualquer lugar. Em outros clientes MCP o formato é o mesmo:

{ "mcpServers": { "browser-ai": { "command": "web-ai", "args": ["mcp"] } } }

Ferramentas expostas ao agente

Ferramenta

O que faz

web_tabs

Lista as abas (id, título, url).

web_new_tab

Abre uma aba (opcionalmente numa URL).

web_close_tab

Fecha uma aba pelo id.

web_navigate

Navega uma aba para uma URL.

web_read

Texto visível da página (+ título e url).

web_html

outerHTML da página ou de um seletor CSS.

web_click

Clica por seletor CSS ou pelo texto visível.

web_type

Digita num campo (seletor), com submit opcional.

web_wait

Espera um elemento aparecer.

web_eval

Roda JavaScript na página (a ferramenta "coringa").

web_screenshot

PNG da aba (para IAs com visão).

web_download_pdf

Salva a página atual como PDF e retorna o caminho do arquivo.

web_switch_tab

Traz uma aba para frente / torna ativa, pelo id.

web_back

Volta uma entrada no histórico da aba (botão Voltar).

web_forward

Avança uma entrada no histórico da aba (botão Avançar).

Toda ferramenta aceita target_id para escolher a aba; sem ele, usa a primeira.

Segurança

  • web_eval executa JS arbitrário na página — é o que torna o agente realmente útil, mas é poderoso. Desligue com WEBAI_NO_EVAL=1 (ou WEBAI_ALLOW_EVAL=0) em máquina compartilhada/sensível.

  • Use sempre um --user-data-dir dedicado. Não aponte para o perfil onde você fica logado em banco, e-mail etc., a menos que seja proposital.

  • A porta de debug (9222) dá controle total do navegador a quem alcançá-la. Deixe em 127.0.0.1 e não exponha na rede.

Variáveis de ambiente

Variável

Padrão

Para quê

WEBAI_HOST

127.0.0.1

Host da porta de debug.

WEBAI_PORT

9222

Porta de debug do Chrome.

WEBAI_NO_EVAL

—

1 desliga o web_eval.

WEBAI_DOWNLOAD_DIR

~/Downloads

Pasta padrão dos PDFs de web_download_pdf.

WEBAI_DEBUG

—

1 inclui traceback nos erros de ferramenta.

Testes

python3 -m pytest -q      # 11 testes, sem precisar de Chrome aberto

Licença

MIT.

Available Tools

15 tools
web_backA

Go back one entry in the tab's history (like the browser's Back button).

Inputs: target_id.

web_clickA

Click an element by CSS 'selector', or the first clickable element whose visible text contains 'text'.

Inputs: text, selector, target_id.

web_close_tabC

Close a tab by id.

Inputs: target_id (required).

web_download_pdfA

Save the current page as a PDF and return the file path. Optional 'path' (a file or a folder); defaults to ~/Downloads named after the page title.

Inputs: path, target_id.

web_evalB

Run arbitrary JavaScript in the page and return the result. The power tool; can be disabled with WEBAI_NO_EVAL.

Inputs: expression (required), target_id.

web_forwardB

Go forward one entry in the tab's history (like the browser's Forward button).

Inputs: target_id.

web_htmlC

Get outerHTML of the page, or of the element matching 'selector'.

Inputs: selector, max_chars, target_id.

web_navigateC

Navigate a tab to a URL.

Inputs: url (required), target_id.

web_new_tabB

Open a new tab, optionally at a URL. Returns its id.

Inputs: url.

web_readB

Read the visible text of the page (document.body.innerText), with title and URL.

Inputs: max_chars, target_id.

web_screenshotC

Capture a PNG screenshot of the tab.

Inputs: target_id.

web_switch_tabC

Bring a tab to the front / make it active, by id.

Inputs: target_id (required).

web_tabsA

List the open browser tabs (id, title, url).

Inputs: no named parameters.

web_typeB

Type 'text' into the input/textarea matching 'selector'. Set submit=true to submit the form.

Inputs: selector (required), text, submit, target_id.

web_waitA

Wait until an element matching 'selector' appears (polls), up to timeout_seconds.

Inputs: selector (required), target_id, timeout_seconds.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 15 tools

    Disambiguation5/5

    Each tool maps to a distinct browser action: tab lifecycle (list/new/close/switch), history (back/forward), navigation, inspection (read/html/eval/screenshot/pdf), and interaction (click/type/wait). The only mild overlap is web_eval versus web_read/web_html, but eval's arbitrary-JS purpose is clearly differentiated. An agent can reliably pick the right tool for a given intent.

    Naming Consistency4/5

    All tools share a consistent 'web_' snake_case prefix, which makes the set instantly recognizable. Minor deviation: some names are verbs (web_click, web_navigate) while others are nouns (web_tabs, web_screenshot, web_html), but the convention remains readable and predictable.

    Tool Count5/5

    Fifteen tools is well within the sweet spot and each one earns its place by covering a real browser primitive. There is no redundancy or filler in the surface.

    Completeness4/5

    Core lifecycle is fully covered: tab management, navigation, history, content extraction, interaction, waiting, and export (screenshot/PDF). Notable gaps remain for common automation needs — hover, select-option for dropdowns, keyboard key presses, scrolling, and iframe/frame targeting — which agents may have to work around via web_eval.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers