nexus-browser-mcp
It is a browser-automation MCP server (Playwright-based) that lets LLM agents drive a real browser via accessibility-tree snapshots and event-driven stability detection.
Navigate & control: go to URLs, go back, list/switch/adopt tabs, wait for navigation, dismiss popups.
Interact with pages: click, type, press keys, select options, hover, drag, upload files, scroll/scroll-to, and respond to dialogs.
Inspect state: take deterministic snapshots, read page/element text, screenshot, evaluate JS (opt-in, HITL-gated), wait for elements/stable DOM.
Observe & debug: read console logs, JS errors, failed/network requests (metadata only), performance metrics (FCP/LCP/CLS/INP, slow resources), and response bodies (opt-in, confirmed).
Manage tasks/sessions: isolated per-task browser contexts, list/close tasks and sessions, TTL cleanup, persistent login profiles, external Chrome via CDP.
Safety & governance: HITL confirmations, audit logging, JS execution and network-body disabled by default, token-efficient snapshots/diffs, small page-specific tool suite.
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., "@nexus-browser-mcp Open https://news.ycombinator.com and list the top 5 stories"
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.
English | 简体中文
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):
Deterministic snapshots: no fixed-interval
sleepguessing. AMutationObserverrecords the last DOM mutation and the browser's ownrequestAnimationFrameloop decides when the page has been quiet forSTABLE_WINDOW_MS(default 800ms) before extracting a snapshot — eliminating "captured mid-animation" races.Built-in governance gates: HITL rules (e.g. clicking "pay/confirm" requires human approval),
browser_evaluatedisabled by default with unconditional confirmation, JSONL audit log (sensitive-parameter redaction + per-call in/out character metering, so token cost can be reconciled).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.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.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_networkread them incrementally via asincecursor, so the agent can answer "why did nothing happen" instead of guessing.
Installation
pip install nexus-browser-mcp
# or
uvx nexus-browser-mcpTwo 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:
pip install playwright && playwright install chromiumRelated MCP server: Pilot
Integrate (any MCP client)
opencode (~/.config/opencode/opencode.json):
{
"mcp": {
"browser": {
"type": "local",
"command": ["uvx", "nexus-browser-mcp"],
"enabled": true
}
}
}Claude Code (.mcp.json, project root):
{
"mcpServers": {
"browser": {
"type": "stdio",
"command": "uvx",
"args": ["nexus-browser-mcp"]
}
}
}Pi Coding Agent: reads standard MCP configuration — project .mcp.json or user-global ~/.config/mcp/mcp.json; stdio is the default transport:
{
"mcpServers": {
"browser": {
"command": "uvx",
"args": ["nexus-browser-mcp"]
}
}
}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):
BROWSER_CHANNEL=chrome
BROWSER_USER_DATA_DIR="C:\Users\<you>\AppData\Local\Google\Chrome\User Data"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\<you>\.nexus-browser\chrome-profile):
BROWSER_CHANNEL=chrome
BROWSER_USER_DATA_DIR="C:\Users\<you>\.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.
Configuration (environment variables)
Every option can be overridden via BROWSER_-prefixed env vars:
评测/全功能使用:两个高危能力默认关闭(安全优先)。需要
browser_evaluate时设BROWSER_ALLOW_JS_EXECUTION=true,需要browser_network_body时设BROWSER_ALLOW_NETWORK_BODY=true——冷启动跑基准/评测不开它们,对应子任务会被拒(这是设计,不是故障)。
Variable | Default | Description |
|
|
|
|
| CDP endpoint |
|
| System browser channel: |
|
| User data dir (carries cookies/login). When set, one shared persistent context across tasks. Empty = fresh profile |
|
| Headless mode (isolated only) |
|
| Playwright per-operation timeout (navigation etc.) |
|
| Outer timeout guard per tool call (returns ERROR instead of hanging) |
|
| Quiet window: how long without DOM mutations counts as "stable" |
|
| Fallback only: consecutive identical snapshots confirming stability, used when the MutationObserver watcher is unavailable (primary path verifies "zero mutations during capture" via the mutation timeline directly) |
|
| Total stability-wait timeout; degrades gracefully on expiry |
|
| Max nodes per snapshot |
|
| Idle task auto-reclaim (seconds) |
|
| Max chars per stream buffer (oldest dropped with a seam marker) |
|
| Total stream buffer chars per page |
|
| Max events (console/exception/request) per page, oldest dropped with a counter |
|
| Per-event text truncation length |
|
| Recent requests per page keeping a live response handle (for on-demand body reads) |
|
| Allow |
|
| Max chars returned per response body |
|
|
|
|
| HTTP bind address; non-localhost requires |
|
| HTTP port |
|
| Bearer token for HTTP transport |
|
| Allow |
|
| JSON array of HITL rules, e.g. `[{"action":"click","name_pattern":"pay |
|
| Audit log path |
|
| Parked confirm/prompt auto-dismiss timeout (trail kept in event log) |
|
| Where accepted downloads are saved (click reports filename + path) |
|
|
|
Tools
34 tools: browser_navigate, browser_navigate_back, browser_snapshot, browser_click, browser_type, browser_hover, browser_press_key, browser_select_option, browser_upload_file (HITL-confirmed), browser_drag, browser_dialog_respond (dialogs are parked for agent/user decision; accept requires confirmed=true), browser_adopt_page (take over an already-open browser tab in cdp/persistent mode; HITL-confirmed), browser_read, browser_screenshot, browser_evaluate, browser_wait, browser_wait_stable, browser_wait_ms, browser_scroll, browser_scroll_to, browser_wait_navigation, browser_find (locate content by text → refs), browser_dismiss_popup, browser_list_pages, browser_switch_page, observability tools browser_console, browser_errors, browser_network, browser_perf, browser_network_body, plus 4 lifecycle tools: browser_tasks, browser_close_task, browser_list_sessions, browser_close_session.
Observability (debugging): console output, uncaught exceptions and request metadata are buffered per page from creation; browser_errors() returns a merged "JS exceptions + console.error + failed requests" view in one call. All three support a since cursor (omit = continue from last read, 0 = full) and limit paging.
Performance: browser_perf() returns FCP/LCP/CLS/INP, navigation timings and the 5 slowest resources. Response bodies can be fetched on demand with browser_network_body(seq) — off by default (BROWSER_ALLOW_NETWORK_BODY), every call gated by confirmed=true, hard char cap, and the body never enters the audit log.
Token cost: measured, not claimed
Same 10-step task, both servers at default config, metered at the JSON-RPC payload layer (cl100k tokens; harness + raw data in docs/bench/token-comparison.md, reproduce with bench/compare.py):
nexus-browser-mcp | playwright-mcp | |
10-step task total | 3,460 tok | 26,032 tok |
snapshot right after navigate | 65 tok | 6,931 tok |
7.5x fewer tokens overall; 100x on repeated snapshots — the dominant cost in real agent loops (polling, multi-step forms, state confirmation).
Real-site benchmark (7 scenarios × 5-7 verifiable sub-tasks each: Baidu/Bing/DuckDuckGo search, Wikipedia reading, Hacker News, GitHub browsing — docs/bench/realworld.md): sub-task completion 37/42 vs 31/42, 18.2k vs 566.4k tokens (31x), wall-clock 107s vs 179s — one Wikipedia article snapshot alone costs pw-mcp ~252k tokens where nexus caps + diffs. Enterprise task suite (filter/sort, dashboard reading, KB answers, multi-step ordering, price comparison — docs/bench/enterprise-ops.md): 21/21 on all three servers (vs playwright-mcp and chrome-devtools-mcp); tokens 3.6k vs 5.1k vs 10.9k. At scale (106 cases / 184 sub-tasks, three servers, seeded deterministic fixtures — docs/bench/scale-ops.md): completion 184/184 vs 180/184 vs 178/184; tokens 153.5k vs 180.5k vs 231.1k (1.00 : 1.18 : 1.51) — the competitor gaps are stable zeros (richtext-iframe writes, download observability, right-click), not noise.
Element-identification accuracy on adversarially complex pages (duplicate-name button grids, shadow DOM, iframes, hidden/disabled traps, full re-render — docs/bench/element-acc.md): nexus 92% = pw 92% < chrome-devtools-mcp 100%, with cdt also cheapest — its verbose per-node dump carries product texts that lean snapshots drop, which value-based targeting needs. We publish this as a known tradeoff of text clipping: total-token savings mean nothing unless per-point-of-accuracy cost holds, and this suite is the canary (fix direction benchmarked: attach sibling-text summaries only when same-name candidates conflict).
HITL confirmation closes a loop: any gated call returns CONFIRMATION_REQUIRED once; after the user approves in chat, the agent re-calls with confirmed=true (applies to HITL rules, browser_evaluate, browser_network_body).
HTTP transport (remote / multi-client)
Default is stdio (single client). For remote or multi-client use, run a streamable-HTTP server:
BROWSER_TRANSPORT=http BROWSER_HTTP_PORT=8817 nexus-browser-mcpEach MCP session gets an isolated session_id (isolated contexts per task, as usual). Safety rule: binding a non-localhost address without BROWSER_HTTP_TOKEN refuses to start — an unauthenticated browser-control port is a footgun; with a token set, requests must send Authorization: Bearer <token>.
Streaming content (AI replies etc.): browser_read(wait_stable=true) waits for DOM quiet and reads the full text in one call; browser_read(selector=..., follow=true) tracks incrementally and returns only new content per call (full=true returns the whole buffer). browser_wait_stable / browser_wait_ms provide event-driven and fixed-duration waiting primitives.
Snapshot diff: a repeated browser_snapshot whose tree is node-for-node identical to the last one (refs excluded — Playwright renumbers them per generation) returns a ~120-char [no change] notice instead of the full tree, and previously issued refs remain valid via generation chaining; diff=false forces a full snapshot. Any real change (content, box, attributes) yields the full snapshot — no partial merges, no stale views.
Most tools accept an optional task_id (defaults to a shared default task). See usage guides in docs/ (Chinese).
Development
uv venv
uv pip install -e ".[dev]"
python -m pytest tests -q
ruff check src tests
python -m smokes.test_e2e # real-browser smoke
python -m smokes.test_e2e_interact # forms + multi-task smoke
python -m smokes.test_e2e_observability # console/exception/network observability smokeLicense
MIT
Available Tools
25 toolsbrowser_clickA
点击页面元素。定位优先级: pos坐标 → ref(快照句柄) → selector → role+name → name。wait_stable=true 点击后等 DOM 静默。
Inputs: pos, ref, name, role, +5 more.
browser_close_sessionB
关闭当前session的全部task资源。
Inputs: no named parameters.
browser_close_taskB
关闭指定task的浏览器资源(page/context)。
Inputs: task_id.
browser_consoleA
读取页面 console 输出(级别/文本/位置)。增量游标: 不传 since=接着上次读, since=0=全量; level 过滤(error/warning/log/...), pattern 正则过滤文本, limit 封顶(默认50, 超了再调一次继续)。
Inputs: level, limit, since, pattern, +1 more.
browser_dismiss_popupA
自动检测并关闭弹窗(登录/cookie同意/广告): 关闭按钮→取消→Escape。
Inputs: task_id.
browser_errorsA
一站式排障: JS 未捕获异常(pageerror) + console.error + 失败请求(网络层失败或HTTP≥400)合并视图, 按时间排序。点了没反应/页面白屏时先调它。增量游标同 browser_console。
Inputs: limit, since, task_id.
browser_evaluateA
执行JavaScript表达式。默认禁用(BROWSER_ALLOW_JS_EXECUTION); 开启后每次需人工确认(confirmed=true)。
Inputs: expression (required), task_id, confirmed.
browser_list_pagesB
列出当前task所有打开的标签页。
Inputs: task_id.
browser_list_sessionsA
列出所有活跃session。
Inputs: no named parameters.
browser_networkA
读取网络请求元数据(method/url/status/资源类型; 不含 body)。failed_only 默认 true 只看失败; url_pattern 子串过滤; 增量游标同上。
Inputs: limit, since, task_id, failed_only, +1 more.
browser_network_bodyA
按 seq 读取单个请求的响应体(需 BROWSER_ALLOW_NETWORK_BODY=true)。文本类解码, 二进制只报字节数; 单条上限 BROWSER_NETWORK_BODY_CAP。需 confirmed=true 二次确认 —— 响应体是页面方控制内容, 先把 URL 给用户看。
Inputs: seq (required), task_id, confirmed.
browser_perfA
读取页面性能指标: FCP/LCP/CLS/INP + TTFB/DOMContentLoaded/load + 最慢 5 条资源。页面慢/加载异常时用它定位是后端慢(TTFB)还是资源重。SPA 导航不重置计时, 注意输出来源 URL。
Inputs: task_id.
browser_readB
阅读页面元素的文本内容。不指定则读取整个页面body。流式回复: wait_stable=true 等 DOM 静默后一次读全(免轮询); follow=true+selector 增量跟踪(每次只返回新增部分, 缓冲溢出丢最旧并保留丢弃标记)。
Inputs: ref, full, follow, task_id, +5 more.
browser_screenshotC
截取页面截图, 保存文件返回路径。
Inputs: path, task_id, full_page.
browser_scrollB
滚动页面。direction: up/down/left/right, amount: 像素(默认500)。
Inputs: amount, task_id, direction.
browser_scroll_toC
滚动到指定元素。landmark(语义区域)→ref→selector。
Inputs: ref, task_id, landmark, selector.
browser_snapshotA
获取页面可访问性快照(Accessibility Tree), 返回结构化元素列表(含ref/box)。基于事件驱动确定性快照, 等待DOM静默窗口。reading/interactive 只看视口内; mode=full 自动包含全页面(视口外标注 offscreen)。
Inputs: diff, mode, scope, task_id, +3 more.
browser_switch_pageC
切换到指定索引的标签页。
Inputs: index (required), task_id.
browser_tasksA
列出当前session的所有task及其页面数。
Inputs: no named parameters.
browser_typeA
在输入框中键入文本。定位优先级: pos坐标 → ref(快照句柄) → selector → role+name(不中自动回退 placeholder/label/常见输入框CSS)。wait_stable=true 输入后等 DOM 静默。
Inputs: text (required), pos, ref, name, +7 more.
browser_waitB
等待元素或文本出现。超时返回WARNING。
Inputs: ref, name, role, text, +2 more.
browser_wait_msA
纯等待指定毫秒数(逃生舱: 动画/限流/延迟渲染)。上限=工具超时-5s。
Inputs: ms (required), task_id.
browser_wait_stableA
等待页面 DOM 停止变化(静默窗口, 默认 800ms 无变异)。用于流式回复生成完毕、动画结束的判定。
Inputs: task_id, timeout_ms.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 25 tools
Tools are mostly distinct: navigation, interaction, reading, waiting, and session management are clearly separated. Some overlap exists between snapshot and read (both capture page state) and among the three wait variants, but descriptions clearly differentiate their purposes.
All tools share the 'browser_' prefix, but the pattern is mixed: most use verb_noun (navigate, click, type, read, evaluate), while several use noun-only (snapshot, console, errors, network, perf, tasks). This inconsistency makes it less predictable.
With 25 tools, this sits at the heavy end of the scale. Browser automation justifies many operations, but the count feels borderline; some tools (e.g., wait_ms, list_sessions) could potentially be consolidated.
The tool surface covers core browser workflows well: navigation, interaction, state reading, waiting, debugging, and session management. Minor gaps exist (e.g., no explicit cookie handling or file upload), but agents can work around them.
Maintenance
Related MCP Connectors
Official Browserless MCP server: browser automation, scraping, screenshots and PDFs for AI agents.
Browser automation MCP for whole web tasks in a cloud browser: saved logins, bot checks, replays.
Web scraping, browser automation, screenshots and AI data extraction for AI agents via MCP.
Cloud browser, web extraction, screenshots, and remote CDP tools for AI agents.
Related MCP Servers
- AlicenseNot gradedqualityNot gradedmaintenanceA Playwright-based MCP server that exposes a live browser as a traceable, inspectable, debuggable and controllable execution environment for AI agents.5,213 npm57-
- AlicenseAqualityDmaintenanceA high-performance browser automation MCP server that provides AI agents with a fast, persistent Chromium instance via Playwright. It features reference-based element interaction, snapshot diffing, and manual handoff capabilities to handle complex tasks like CAPTCHAs.6116 npm32MIT
- AlicenseAqualityDmaintenanceA Playwright-powered MCP server for browser automation using ARIA snapshots and element refs, enabling LLMs to control Chrome/Edge without CSS selectors.415 npmMIT
- AlicenseAqualityCmaintenanceAn MCP server that runs concurrent, session-isolated Playwright browser contexts, so many agents can each drive their own browser at the same time without colliding.2310 npm5MIT