browser-mcp-server
Enables an AI agent to drive the user's real Google Chrome (using its existing logged-in sessions) to navigate URLs, click elements, fill form fields, capture screenshots, read page content and links, and wait for elements or text. Useful for automating web flows that would otherwise need manual intervention, such as deploys and configuration in web dashboards.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@browser-mcp-server navigate to example.com and take a screenshot of the page"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
browser-mcp-server
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 |
| Abre uma URL e aguarda o carregamento |
| Clica por seletor CSS, texto visível ou aria-label |
| Preenche um campo de formulário |
| Salva um PNG da página |
| Lê título, URL, texto visível e links |
| 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 installA 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-profileA 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 |
| perfil temporário dedicado | Diretório de dados do Chrome (mantém logins) |
|
| Perfil dentro do diretório |
|
| Onde salvar screenshots |
|
| Arquivo de auditoria |
|
|
|
|
| Timeout das operações (ms) |
|
| Termos bloqueados no hostname |
Caminhos típicos do perfil:
Windows:
C:\Users\<usuario>\AppData\Local\Google\Chrome\User DatamacOS:
~/Library/Application Support/Google/ChromeLinux:
~/.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
Available Tools
6 toolsbrowser_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_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
Scored across 6 tools
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).
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.
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.
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
Related MCP Connectors
Give AI agents a real cloud Chrome: open sessions, navigate, read pages, click, type and screenshot.
Control a real browser from AI agents: navigate, click, type, screenshot, read the page.
Hosted browser for agents: open pages, search the web, extract data, read PDFs and take screenshots.
Playwright browser automation — navigate, click, fill forms, extract, screenshot — 17 agent tools.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables browser automation and web interaction control through Playwright, allowing Claude Code to navigate, click, fill forms, take screenshots, and manage sessions.100 npm9MIT
- FlicenseAqualityDmaintenanceGives Claude control of a real, headed Chromium browser via Playwright, enabling web navigation, clicking, typing, screenshots, and JavaScript evaluation.8-
- AlicenseNot gradedqualityDmaintenanceEnables 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 npmMIT
- AlicenseBqualityCmaintenanceEnables 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.6ISC