Skip to main content
Glama
browser-mcp-server

browser-mcp-server

by vicktor12

browser-mcp-server

CI License: MIT

Servidor MCP local (Node.js + Playwright) que permite ao Claude Code controlar o Google Chrome: navegar, clicar, preencher formulários, tirar screenshots e ler páginas. Útil para completar fluxos que exigiriam intervenção manual (deploys em painéis web, parametrizações em sistemas etc.), usando as sessões já logadas do seu perfil do Chrome.

Aviso: dá a um agente de IA controle de um navegador com suas sessões reais. Leia docs/security.md antes de usar.

Tools

Tool

O que faz

browser_navigate

Abre uma URL e aguarda o carregamento

browser_click

Clica por seletor CSS, texto visível ou aria-label

browser_fill

Preenche um campo de formulário

browser_screenshot

Salva um PNG da página

browser_read_page

Lê título, URL, texto visível e links

browser_wait_for

Aguarda elemento ou texto

Detalhes de parâmetros em docs/tools.md.

Related MCP server: browser-for-claude

Requisitos

  • Node.js 20+

  • Google Chrome instalado (usa o Chrome real, não o Chromium do Playwright)

Instalação

git clone https://github.com/vicktor12/browser-mcp-server.git
cd browser-mcp-server
npm install

A configuração do servidor é passada pelo próprio registro no Claude Code (-e VAR=valor, abaixo). O .env (cp .env.example .env) só é lido quando o servidor roda a partir da pasta do projeto (ex.: npm run test:e2e); quando o Claude Code o inicia, o diretório de trabalho é outro e o .env é ignorado.

Registrar no Claude Code

claude mcp add browser --scope user \
  -e "CHROME_USER_DATA_DIR=<caminho do perfil>" \
  -e CHROME_PROFILE=Default \
  -- node "<caminho absoluto>/browser-mcp-server/index.js"

Reinicie o Claude Code e confira com claude mcp list. Alternativamente, copie claude-settings.example.json para .mcp.json na raiz do seu projeto (configuração de MCP por projeto) e ajuste o caminho.

Feche o Chrome por completo antes de usar — o Playwright precisa de acesso exclusivo ao perfil.

Chrome 136+: use uma cópia do perfil

O Chrome 136+ recusa automação no diretório de dados padrão (DevTools remote debugging requires a non-default data directory). Por isso, aponte CHROME_USER_DATA_DIR para uma cópia do perfil. No Windows, com o Chrome fechado:

./scripts/copy-chrome-profile.ps1     # copia para %USERPROFILE%\.browser-mcp-profile

A cópia mantém cookies e logins do momento da cópia; rode o script de novo para atualizar as sessões. A cópia contém dados sensíveis (sessões): mantenha-a fora de repositórios e de pastas sincronizadas. Em macOS/Linux, copie o diretório do perfil manualmente para outro caminho.

Configuração

Tudo por variáveis de ambiente (ver .env.example):

Variável

Padrão

Descrição

CHROME_USER_DATA_DIR

perfil temporário dedicado

Diretório de dados do Chrome (mantém logins)

CHROME_PROFILE

Default

Perfil dentro do diretório

SCREENSHOTS_DIR

<tmpdir>/browser-mcp-screenshots

Onde salvar screenshots

AUDIT_LOG

<tmpdir>/browser-mcp-audit.log

Arquivo de auditoria

BROWSER_HEADLESS

false

true roda sem janela

BROWSER_TIMEOUT

15000

Timeout das operações (ms)

BLOCKED_DOMAINS

banco,pagamento,financeiro,pix,transferencia

Termos bloqueados no hostname

Caminhos típicos do perfil:

  • Windows: C:\Users\<usuario>\AppData\Local\Google\Chrome\User Data

  • macOS: ~/Library/Application Support/Google/Chrome

  • Linux: ~/.config/google-chrome

Como o agente deve usar

Toda chamada deve incluir [AGENT-BROWSER-TASK] em task_description, com o que está sendo feito e por quê:

[AGENT-BROWSER-TASK] Acessando painel de hospedagem para realizar deploy
da versão 1.2.0 do sistema. Ação: clicar no botão Deploy na aba Production.
Risco identificado: nenhum. Credenciais: não serão inseridas nesta sessão.

Sem o marcador (ou com qualquer padrão de risco) o guard bloqueia a chamada e devolve um erro descritivo.

Login: o guard bloqueia campos de senha/token (password, secret, token...). Faça login no site manualmente na cópia do perfil (ou deixe a sessão já salva nela) e só então peça ao agente para operar. O agente não digita credenciais.

Desenvolvimento

npm test          # testes unitários (sem browser)
npm run lint      # ESLint
npm run test:e2e  # fluxo real contra example.com (precisa de Chrome; BROWSER_HEADLESS=true para não abrir janela)

Mais em docs/architecture.md e CONTRIBUTING.md.

Limitações conhecidas

  • O Chrome deve estar fechado quando o servidor iniciar (conflito de perfil).

  • Chrome 136+ recusa automação sobre o diretório de dados padrão: use uma cópia do perfil (ver acima). Sessões na cópia não se sincronizam com o seu Chrome do dia a dia.

  • Páginas com 2FA exigem intervenção manual prévia.

  • Sites com anti-bot pesado (ex.: Cloudflare challenge) podem bloquear.

  • Uma única aba ativa; sem suporte a múltiplas abas.

Licença

MIT

Available Tools

6 tools
browser_clickA

Clica em um elemento da página. Pode encontrar o elemento por seletor CSS, por texto visível ou por aria-label. Tenta as estratégias em ordem até encontrar.

Inputs: task_description (required), text, selector, aria_label.

browser_fillC

Preenche um campo de formulário (input, textarea, select). Limpa o campo antes de digitar.

Inputs: value (required), selector (required), task_description (required), clear_first, +1 more.

browser_navigateB

Navega para uma URL no browser. Sempre chame esta tool antes de interagir com qualquer página. Aguarda o carregamento completo.

Inputs: url (required), task_description (required), wait_until.

browser_read_pageA

Lê o conteúdo atual da página: título, URL, texto visível e lista dos links disponíveis. Usar para entender o estado da página antes de agir.

Inputs: task_description (required), include_links, max_text_length.

browser_screenshotB

Tira screenshot da página atual e salva em disco. Usar para confirmar o resultado de ações ou capturar estado de erro.

Inputs: task_description (required), filename, full_page.

browser_wait_forB

Aguarda um elemento aparecer, desaparecer ou um texto surgir na página. Útil após ações que disparam carregamentos assíncronos.

Inputs: task_description (required), text, state, timeout, +1 more.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 6 tools

    Disambiguation5/5

    Each tool maps to a distinct browser action: navigation, clicking, form filling, screenshot capture, page reading, and waiting. There is no meaningful overlap between them, and the descriptions reinforce clear boundaries (e.g., navigate before acting, read_page before deciding).

    Naming Consistency5/5

    All six tools use a strict browser_<verb> or browser_<verb>_<noun> snake_case pattern (browser_navigate, browser_click, browser_fill, browser_read_page). The convention is uniform and immediately readable.

    Tool Count5/5

    Six tools is a tight, well-scoped set for browser automation, with each tool earning its place and no redundant entries. It covers the observe-act-wait loop without bloat.

    Completeness4/5

    The core loop of navigate, read, interact (click/fill), wait, and capture is fully covered for most web tasks. Minor gaps exist for actions like scrolling, keyboard presses, hover, or back/forward navigation, but agents can largely work around these via clicks and fills.

    Maintenance

    ActivitySlowing
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables browser automation and web interaction control through Playwright, allowing Claude Code to navigate, click, fill forms, take screenshots, and manage sessions.
      100 npm
      9
      MIT
    • F
      license
      A
      quality
      D
      maintenance
      Gives Claude control of a real, headed Chromium browser via Playwright, enabling web navigation, clicking, typing, screenshots, and JavaScript evaluation.
      8
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables Claude Code to control a browser via Playwright for web scraping, automation, and research, with features like navigation, screenshots, form filling, and PDF export.
      24 npm
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      Enables AI assistants to control a real Chromium browser through Playwright, allowing them to navigate pages, click elements, fill forms, extract text or HTML, and capture screenshots in a persistent session.
      6
      ISC