Content
# chrome-hook MCP
A local [MCP](https://modelcontextprotocol.io) 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](./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
```bash
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)
```toml
[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)
```text
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.
```text
# 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
```text
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.
