chrome-hook MCP

A local MCP server that drives real Chromium browsers (Chrome / Brave) for multi-account testing and full network capture, with a real-browser attach path for strict bot protection.

See CHANGELOG.md for recent behavior changes (optional proxy, no legacy auth seeds, public-doc hygiene).

Built on patchright (a drop-in Playwright with CDP-layer anti-detection patches), falling back to stock Playwright when patchright is absent.

Cross-platform (macOS / Windows / Linux). Chrome and Brave binaries are auto-detected from standard install locations and PATH — no hardcoded paths. The stealth UA is derived from the installed browser's version and the host OS.

Local-only. Everything runs on your machine. Captured traffic, cookies, auth state and browser profiles are written to local disk and are never uploaded anywhere. Do not commit the runtime dirs (see .gitignore).

---

What it does

• Named browser slots (a, b, …) run side by side so you can test two accounts at once without logging out (servers often revoke tokens on logout — use two slots instead of switching).
• Project-scoped auth/profiles (project= isolates cookies per site so accounts never bleed across projects).
• Full capture by default: every HTTP(S) request/response + WebSocket frame, streamed to network.jsonl, saved bodies, and an exportable HAR.
• Strict bot protection: patchright driver + a real-browser attach mode (Plan A) that gets past managed challenges a cold automated browser can never solve.
• Optional proxy: off by default; set CHROME_HOOK_PROXY or proxy= when needed.

---

Install

pip install -r requirements.txt
# patchright ships its own patched driver; using channel="chrome"/"brave" (real
# binaries) means you do NOT need a separate `patchright install chromium` download.

Requires a real Google Chrome and/or Brave installed. Their binaries are auto-located on macOS, Windows, and Linux (standard install dirs + PATH).

Register with your MCP host (e.g. Grok CLI)

[mcp_servers.chrome-hook]
command = "python3"
# Prefer the installed runtime path (Grok loads this); keep in sync with repo.
args = ["/ABS/PATH/TO/chrome-hook-mcp/server.py"]  # or ~/.grok/tools/chrome-hook-mcp/server.py
enabled = true
startup_timeout_sec = 45
tool_timeout_sec = 180
# Proxy is optional (off by default). Uncomment when you need Burp/Clash:
# env = { CHROME_HOOK_PROXY = "http://127.0.0.1:8080" }

After editing server.py, copy to the installed path if needed, then restart the MCP host.

Agent workflows live in companion skill chrome-hook-browser (SKILL.md in this repo and ~/.grok/skills/chrome-hook-browser/).

---

Two ways to use it

1. Normal launch (most sites)

browser_launch(project="acme", slot="a", headless=false,
               start_url="https://example.com/")
browser_launch(project="acme", slot="b", headless=false,
               start_url="https://example.com/")   # second account, no logout
# ... log in each window the first time ...
browser_persist(slot="a"); browser_persist(slot="b")   # save auth
# later runs auto-restore — no re-login while the token is valid
browser_request(..., slot="a")

Anti-bot hardening applied automatically: patchright driver; UA auto-matched to the installed Chrome major version; locale/timezone_id left native under patchright (forcing e.g. en-US on an Asia machine is itself a Cloudflare mismatch flag); a JS stealth init-script is injected only on the stock-Playwright fallback.

2. Plan A — attach to a real, warm browser (strict bot protection)

Some sites hand a cold/freshly-launched automated browser an unsolvable managed challenge — even under patchright, even if you click the checkbox by hand. The reliable fix is to attach to a genuine, already-warmed browser that you passed the challenge in.

# step 1 — spawn YOUR real browser with a remote-debugging port + dedicated profile
browser_open_real(project="demo", slot="a",
                  url="https://example.com/",
                  port=9222, browser="brave")     # browser: "chrome" | "brave"

#   -> solve the challenge by hand in the window that opens

# step 2 — MCP connects over CDP and captures the warm session
browser_attach(project="demo", slot="a", port=9222)

Why this works, and the details that matter:

• Brave (browser="brave") often clears strict challenges where a cold Chrome profile cannot, thanks to its built-in anti-fingerprinting. The dedicated profile lives in real-chrome/<project>/<slot>[-brave]/ and is reused across runs, so once you pass the challenge the clearance cookie persists and you rarely have to solve it again.
• It uses a separate profile from your everyday browser (a running browser locks its own profile and can't expose CDP on it). Your normal browser is untouched.
• A CDP-attached pre-existing tab emits no Playwright network events, so attach opens a fresh capture page in the same context — it inherits the context cookies (incl. clearance tokens), loads past the challenge with no new prompt, and lands on the tab's URL. Capture happens on that page.
• browser_close on an attached slot only disconnects — it never closes your real browser or its original tab, and never overwrites its cookies with stale auth.

browser_launch(cdp_url="http://127.0.0.1:9222", …) is the low-level equivalent of browser_attach.

---

Tools (27)

Session / slots browser_set_project · browser_sessions · browser_focus · browser_launch · browser_status · browser_close

Plan A (real browser) browser_open_real — spawn real Chrome/Brave with a debug port · browser_attach — connect over CDP and capture the warm session

Auth persistence browser_persist · browser_restore · browser_storage_save · browser_storage_load · browser_cookies_get · browser_cookies_set

Page actions browser_navigate · browser_snapshot · browser_click · browser_type · browser_press · browser_wait · browser_screenshot · browser_eval

Network capture / replay browser_network_dump — events under the hits key (count = total) · browser_network_set_filter · browser_network_set_mode (all | api) · browser_export_har · browser_request — issue a request in-context

---

Proxy (optional)

Item	Value
Default	No proxy (direct)
Env	CHROME_HOOK_PROXY (optional, e.g. http://127.0.0.1:8080 Burp)
Per-call	browser_launch(proxy=…) / browser_open_real(proxy=…)
Force off	proxy="none" or CHROME_HOOK_PROXY=none
MITM	When proxy is set, cert errors are ignored automatically
Attach	Does not change the real browser's proxy — set it at open_real time

On-disk layout

chrome-hook-mcp/
  server.py                     # the MCP server (27 tools)
  SKILL.md                      # companion agent skill (chrome-hook-browser)
  requirements.txt
  README.md
  # --- runtime state under ~/.grok/tools/chrome-hook-mcp/ (git-ignored) ---
  profiles/<project>/<slot>/    # Chromium user-data for normal launch
  auth/<project>/<slot>.json    # storage_state auto save/restore
  real-chrome/<project>/<slot>[-brave]/   # Plan A dedicated warm profiles
  sessions/<project>_<slot>_…/  # per-run network.jsonl + HAR + bodies

Defaults: auto_restore=true, auto_save=true (save on close), capture_mode="all", body caps 512 KB HTTP / 64 KB WS, no proxy unless CHROME_HOOK_PROXY or per-call proxy= is set.

---

Notes & limits

• Restart the MCP host after editing server.py — a running process keeps the old code and won't expose new tools.
• Browser-context only (not other OS processes). One Playwright driver thread; multiple Chromium/Brave processes are fine.
• Ad-hoc testing via one-shot python3 -c hits Playwright's thread affinity (greenlet: Cannot switch to a different thread) and EPIPE on repeated connect_over_cdp; the long-lived MCP process is fine. To probe internals in a script, run your function on the driver thread via server._PW.submit(fn).
• Security: never upload captured data, cookies, auth state, or profiles. Keep the runtime dirs local and out of version control.