paipaipai666/nexus-browser-mcp

nexus-browser-mcp
**A browser-automation MCP server with event-driven, deterministic snapshots.**
Built on Playwright. Drives a browser for LLMs through the Accessibility Tree — navigate, click, type, read, fill forms, manage tabs. Key differences from alternatives (e.g. Playwright MCP):
1. **Deterministic snapshots**: no fixed-interval sleep guessing. A MutationObserver records the last DOM mutation and the browser's own requestAnimationFrame loop decides when the page has been quiet for STABLE_WINDOW_MS (default 800ms) before extracting a snapshot — eliminating "captured mid-animation" races.
2. **Built-in governance gates**: HITL rules (e.g. clicking "pay/confirm" requires human approval), browser_evaluate disabled by default with unconditional confirmation, JSONL audit log (sensitive-parameter redaction + per-call in/out character metering, so token cost can be reconciled).
3. **Multi-task isolation**: one MCP connection (session) can host multiple independent task_ids, each with its own BrowserContext (no login-state cross-contamination). Idle tasks are reclaimed by TTL; on next use they're rebuilt and the last page is restored automatically.
4. **Death observability + self-healing**: if a tab or the whole browser is closed externally or crashes, the next call rebuilds it automatically (a persistent profile keeps your login state) and prepends a [state change] notice telling the agent exactly what was restored and what was lost — no raw Playwright exceptions leak through.
5. **Developer observability**: every page records console messages, uncaught JS exceptions and network request metadata (method/URL/status/failure reason — **never bodies**) into capped ring buffers; browser_console / browser_errors / browser_network read them incrementally via a since cursor, so the agent can answer "why did nothing happen" instead of guessing.
Installation
Two executable entry points are installed: nexus-browser-mcp and nexus-browser. A guaranteed fallback: python -m nexus_browser.server.
Requires playwright and its browser binary:
Integrate (any MCP client)
**opencode** (~/.config/opencode/opencode.json):
**Claude Code** (.mcp.json, project root):
**Pi Coding Agent**: reads standard MCP configuration — project .mcp.json or user-global ~/.config/mcp/mcp.json; stdio is the default transport:
See docs/INTEGRATE.md for details (Chinese).
Use your own browser (with login state)
By default, isolated mode launches Playwright's bundled Chromium **without your cookies/login state**. To use your own browser, pick one:
**Option A — load your browser profile directly (recommended, simplest)**
Use system Chrome with your everyday user data directory (cookies/login/bookmarks included):
> Note: while running against your real User Data, the process owns the browser — launching your own Chrome concurrently will conflict. Prefer a copied profile or a dedicated --user-data-dir.
**Recommended: a tool-dedicated profile (no conflict with your daily browser)**
Use BROWSER_CHANNEL=chrome plus a dedicated user data dir (e.g. C:\Users\ \.nexus-browser\chrome-profile):
On first use, log in to target sites once in the dedicated Chrome window that pops up when the agent calls a browser tool. Cookies persist in that profile forever after — the agent carries login state while staying fully isolated from your daily browser.
**Option B — attach to a running Chrome via CDP**
Start chrome --remote-debugging-port=9222 first, then set BROWSER_MODE=cdp.
> If the CDP connection fails, the server now **fails loudly** (no silent fallback to a fresh browser) and tells you to start the debug-port browser first.
In CDP (or persistent-profile) mode the agent can also **take over tabs you already have open**: browser_list_pages shows them under "external tabs", and browser_adopt_page(ext_index) pulls one into the task (snapshot/click/read all work from then on). Adoption always requires confirmed=true — it hands the agent full read/write access to that page, including its login state.