Chrome MCP
Mehmoodqureshi/chrome-mcp
Dirija um Chrome real via Claude com extensão MV3 ou fallback Playwright
Ver no GitHubMCP server que controla um navegador Chrome real via Claude ou qualquer host MCP. Oferece dois backends: uma extensão MV3 que acessa suas logins e cookies reais, e um fallback Playwright/CDP para uso headless. Distribui-se como CLI npx com controle fino de permissões (domínios, mutações, downloads).
Instalação
npx convez-ai Mehmoodqureshi/chrome-mcp1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Automação de navegação com logins reais em websites
- Captura de dados e screenshots de páginas dinâmicas
- Testes end-to-end de aplicações web com interações reais
- Preenchimento de formulários e extração de conteúdo
- Acesso a cookies e armazenamento de sessão autenticada
Veredito

Ferramenta madura (v0.2.0) com arquitetura sólida e fallback CDP. Ideal para quem precisa automação real de browser com contexto autenticado, mas exige config manual e entendimento de segurança (modelo deny-all de permissões é correto, não fraqueza).
README
A tradução para o português deste README ainda está na fila.
chrome-mcp
Drive a real Chrome browser from Claude (or any MCP host). One pluggable
Executor interface, two backends:
- Extension (primary): an MV3 extension drives your real Chrome — real
logins, real cookies — via
chrome.scripting/chrome.tabs. The CLI runs a localhost WebSocket server; the extension dials in. - CDP fallback: when no extension is paired, the CLI launches/attaches a Playwright-driven Chromium for scripted/headless use.
Distributed as an npx CLI (the MCP server) plus a load-unpacked extension.
Full design:
docs/BLUEPRINT.md— architecture, wire protocol, the complete tool surface, the extension manifest, the security model, and the phased build plan.
Quickstart
1. Register the MCP server with your host (e.g. Claude Desktop / Code):
{
"mcpServers": {
"chrome-mcp": {
"command": "npx",
"args": ["-y", "@mehmoodqureshi/chrome-mcp", "--allow-domain", "example.com", "--enable-mutations"]
}
}
}
By default everything is deny-all (no domains, no eval, no mutations). Grant
exactly what you need with --allow-domain <glob> (repeatable), --enable-mutations,
--enable-downloads, --unsafe-enable-eval, or --unsafe-all-domains.
Drive only your real Chrome (recommended for the extension). Add
--no-cdp-fallback so the server never launches a separate Chromium, and
--persist-token so the pairing token survives restarts — pair once, never
again:
{
"mcpServers": {
"chrome-mcp": {
"command": "npx",
"args": ["-y", "@mehmoodqureshi/chrome-mcp",
"--allow-domain", "example.com", "--enable-mutations",
"--no-cdp-fallback", "--persist-token"]
}
}
}
Without --persist-token a fresh token is minted every boot (the secure
default), which means re-pairing the extension on each restart. With it, the
token is stored 0600 at ~/.chrome-mcp/token and reused; the extension's
keepalive auto-reconnects with no manual step. CHROME_MCP_TOKEN pins the token
explicitly (and is never written to disk).
2. Load the extension (to drive your real Chrome): build it, then
chrome://extensions → enable Developer mode → Load unpacked → select
extension-dist/.
3. Pair it: run npx chrome-mcp --print-pairing to write the handshake and
print its path, open the extension's Options page, and paste the port +
token from ~/.chrome-mcp/handshake.json. (Without the extension, the CLI
falls back to a Playwright-driven Chromium automatically.)
The tools cover tabs, navigation, interaction (click/type/press/hover/
scroll/select_option), reads (get_text/get_html/screenshot/eval/wait_for),
an accessibility snapshot (interactive elements with stable refs the model can
target instead of guessing CSS selectors), session access (get_cookies/storage),
helpers (extract_links/read_as_markdown/fill_form/download_file), and
chrome_status.
click/type accept trusted: true for real OS-level input (works on
React/Vue controlled inputs); interactions auto-wait for the target to appear.
Status
v0.2.0 — all six build phases complete and green (57 automated tests + a gated
headed extension smoke). End-to-end working: npx chrome-mcp ⇄ bridge ⇄
extension ⇄ your real Chrome, with a Playwright CDP fallback. v0.2 adds the
accessibility snapshot + element refs, auto-wait, cookies/storage/select_option,
trusted input (chrome.debugger), a toolbar status badge, and a stable pairing
token (--persist-token).
- Phase 0 — Contracts & skeleton:
shared/protocol.ts(wire contract),src/executor/types.ts(Executor interface),src/security/policy.ts(default-deny policy + capability gates),src/config.ts(CLI/env/policy resolution), build + test harness. - Phase 1 — MCP server + StubExecutor:
mcp/server.ts(clean-stdout stdio),mcp/tools.ts(23-tool catalog + never-throw dispatch + drift-check), validators/envelopes/helpers,ExecutorManager+StubExecutor,cli.ts. Point an MCP host atnode dist/src/cli.jstoday. - Phase 2 — WebSocket bridge + auth:
bridge/server.ts(loopback WS, hello-token gate, welcome/unauthorized, displacement),bridge/auth.ts(per-boot 256-bit token, atomic-0600 handshake, SHA-256timingSafeEqual),bridge/connection.ts(id-correlation, method-aware timeouts, backpressure, reject-all-on-close, heartbeat). - Phase 3 — ExtensionExecutor + CdpExecutor + selection:
executor/extension-executor.ts(Executor over the bridge),executor/cdp-executor.ts(Playwright connect/launch + lock recovery + tab resolution),executor/select.ts(extension-if-ping-responsive else CDP). CLI now starts the bridge, writes the 0600 handshake, and serves a real backend. Addsplaywright. - Phase 4 — MV3 extension:
extension/—manifest.json,sw/ws-client.ts(dial + hello/welcome + pong),sw/executor.ts(chrome.scripting/chrome.tabs command impls),sw/router.ts(never-throw + drift),sw/background.ts(top-level listeners + 25s keepalive/reconnect), options page (manual pairing), esbuild build →extension-dist/. Verified by a live--load-extensionsmoke (pair → navigate → get_text). Addsesbuild+@types/chrome. - Phase 5 — Helpers, downloads, HITL: hardened
download_file(shared/download.ts— path-traversal/dangerous-ext sanitize + size cap, wired into both backends), richerread_as_markdown, and a human-in-the-loop harness (hitl/—npm run test:hitl [-- --include-mutating]) with pure, unit-tested gating. 50 automated tests. - Phase 6 — Packaging & docs:
fileswhitelist (shipsdist/src,dist/shared,extension-dist, LICENSE, blueprint — not source/tests),prepackbuild,bin, quickstart +.mcp.jsonsnippet. Verified by a tarball install smoke (npm pack→ install → MCPtools/list).
Security posture (default)
Deny-all safe mode. With no policy configured: empty domain allowlist,
eval off, downloads off, mutating tools off. Opt in explicitly:
chrome-mcp --allow-domain example.com --enable-mutations
chrome-mcp --policy ./policy.json # see policy.example.json
chrome-mcp --unsafe-all-domains # loud footgun
The per-boot 256-bit token in ~/.chrome-mcp/handshake.json (mode 0600) is the
only trust boundary; it is never written to stdout/stderr.
Develop
npm install
npm run typecheck # server/test sources
npm run typecheck:ext # extension sources (@types/chrome)
npm run build:ext # bundle the extension → extension-dist/
npm test # builds, then runs node --test on dist/test
RUN_EXT_SMOKE=1 node --test dist/test/extension-smoke.test.js # live, headed
The extension
extension/ builds (esbuild) to extension-dist/, loaded via
chrome://extensions → Load unpacked → select extension-dist/. Pair it
from the extension's Options page using the port + token from
~/.chrome-mcp/handshake.json (run npx chrome-mcp --print-pairing to get the
path).
v1 uses
chrome.scripting/chrome.tabs, notchrome.debugger. No "is being debugged" banner, CSP-safe reads (isolated world), and it's testable under Playwright. Trade-off: clicks/typing are synthetic DOM events, not OS-level trusted input, andscreenshotis visible-tab only. A trusted-inputchrome.debuggerbackend is a documented future upgrade (BLUEPRINT §10).