nexus-browser-mcp

English | 简体中文

nexus-browser-mcp

一款采用事件驱动、确定性快照的浏览器自动化 MCP 服务。

基于 Playwright 构建。通过无障碍树为大模型驱动浏览器，支持导航、点击、输入、读取、填写表单和管理标签页。与其他方案（如 Playwright MCP）的主要区别：

1. 确定性快照：不再靠固定间隔的 sleep 猜测。MutationObserver 会记录最后一次 DOM 变更，浏览器自身的 requestAnimationFrame 循环则会判断页面何时已稳定 STABLE_WINDOW_MS（默认为 800ms），然后再提取快照，从而消除“在动画中途捕获”的竞态。
2. 内置治理关卡：HITL 规则（例如，点击“支付/确认”需要人工批准）；默认禁用 browser_evaluate，且每次调用都必须确认；JSONL 审计日志（敏感参数脱敏 + 每次调用的输入/输出字符数统计，便于核算 token 成本）。
3. 多任务隔离：一个 MCP 连接（会话）可承载多个相互独立的 task_id，每个任务都有自己的 BrowserContext（登录状态不会相互污染）。闲置任务会按 TTL 回收；下次使用时会重新创建，并自动恢复最后访问的页面。
4. 崩溃可观测性 + 自愈：如果标签页或整个浏览器被外部关闭或发生崩溃，下次调用时会自动重建（持久化配置文件会保留登录状态），并在开头附加 [state change] 通知，明确告知 Agent 恢复了什么、丢失了什么——不会泄漏原始 Playwright 异常。
5. 开发者可观测性：每个页面都会将控制台消息、未捕获的 JS 异常和网络请求元数据（方法/URL/状态/失败原因——绝不记录请求或响应正文）写入有容量上限的环形缓冲区；browser_console / browser_errors / browser_network 可通过 since 游标增量读取，让 Agent 无需猜测，就能回答“为什么什么都没发生”。

安装

pip install nexus-browser-mcp
# or
uvx nexus-browser-mcp

会安装两个可执行入口：nexus-browser-mcp 和 nexus-browser。保证可用的备用方式：python -m nexus_browser.server。

需要 playwright 及其浏览器二进制文件：

pip install playwright && playwright install chromium

集成（适用于任何 MCP 客户端）

opencode（~/.config/opencode/opencode.json）：

{
  "mcp": {
    "browser": {
      "type": "local",
      "command": ["uvx", "nexus-browser-mcp"],
      "enabled": true
    }
  }
}

Claude Code（项目根目录中的 .mcp.json）：

{
  "mcpServers": {
    "browser": {
      "type": "stdio",
      "command": "uvx",
      "args": ["nexus-browser-mcp"]
    }
  }
}

Pi Coding Agent：读取标准 MCP 配置——项目级 .mcp.json 或用户全局配置 ~/.config/mcp/mcp.json；默认传输方式为 stdio：

{
  "mcpServers": {
    "browser": {
      "command": "uvx",
      "args": ["nexus-browser-mcp"]
    }
  }
}

详情请参阅 docs/INTEGRATE.md（中文）。

使用自己的浏览器（保留登录状态）

默认情况下，isolated 模式会启动 Playwright 自带的 Chromium ，不包含你的 Cookie 和登录状态。要使用自己的浏览器，请选择以下一种方式：

选项 A — 直接加载浏览器配置文件（推荐，最简单）

使用系统 Chrome 和你日常使用的用户数据目录（包括 Cookie、登录状态和书签）：

BROWSER_CHANNEL=chrome
BROWSER_USER_DATA_DIR="C:\Users\<you>\AppData\Local\Google\Chrome\User Data"

注意：使用真实的 User Data 运行时，进程会独占浏览器——同时启动自己的 Chrome 会造成冲突。建议使用复制的配置文件，或专用的 --user-data-dir。

推荐：为工具专门创建配置文件（不与日常使用的浏览器冲突）

使用 BROWSER_CHANNEL=chrome，并指定专用的用户数据目录（例如 C:\Users\<you>\.nexus-browser\chrome-profile）：

BROWSER_CHANNEL=chrome
BROWSER_USER_DATA_DIR="C:\Users\<you>\.nexus-browser\chrome-profile"

首次使用时，在 Agent 调用浏览器工具后弹出的专用 Chrome 窗口中登录目标网站一次。之后，Cookie 会永久保存在该配置文件中——Agent 会保留登录状态，同时与你日常使用的浏览器完全隔离。

选项 B — 通过 CDP 连接到正在运行的 Chrome

先启动 chrome --remote-debugging-port=9222，然后设置 BROWSER_MODE=cdp。

如果 CDP 连接失败，服务现在会明确报错（不会悄悄回退到全新浏览器），并提示你先启动带调试端口的浏览器。

在 CDP（或持久配置文件）模式下，Agent 还可以接管已打开的标签页：browser_list_pages 会在“外部标签页”下显示这些标签页，browser_adopt_page(ext_index) 会将其中一个标签页接入当前任务（此后快照、点击和读取操作均可正常使用）。接管始终需要 confirmed=true——这会授予 Agent 对该页面的完整读写权限，包括其登录状态。

配置（环境变量）

每个选项都可以通过带 BROWSER_ 前缀的环境变量覆盖：

评测／全功能使用：两个高危能力默认关闭（安全优先）。需要 browser_evaluate 时设置 BROWSER_ALLOW_JS_EXECUTION=true，需要 browser_network_body 时设置 BROWSER_ALLOW_NETWORK_BODY=true——冷启动运行基准测试／评测时不要启用它们，对应子任务会被拒绝（这是设计如此，并非故障）。

变量	默认值	描述
BROWSER_MODE	isolated	isolated（全新隔离浏览器）／cdp（连接到你的 Chrome）
BROWSER_CDP_ENDPOINT	http://localhost:9222	CDP 端点
BROWSER_CHANNEL	""	系统浏览器通道：chrome／msedge 等（为空 = Playwright 捆绑的 Chromium）
BROWSER_USER_DATA_DIR	""	用户数据目录（包含 Cookie／登录状态）。设置后，所有任务共用一个持久化上下文。为空 = 使用全新配置文件
BROWSER_HEADLESS	false	无头模式（仅适用于 isolated）
BROWSER_DEFAULT_TIMEOUT_MS	30000	Playwright 单次操作超时时间（如导航等）
BROWSER_TOOL_TIMEOUT_MS	60000	每次工具调用的外层超时保护（返回 ERROR，而不是一直挂起）
BROWSER_STABLE_WINDOW_MS	800	静默窗口：DOM 多久没有变化才算“稳定”
BROWSER_STABLE_REQUIRED	2	仅用于回退：用于确认稳定性的连续相同快照数，在 MutationObserver 监视器不可用时使用（主要路径会直接通过变更时间线验证“捕获期间没有变更”）
BROWSER_STABLE_TIMEOUT_MS	3000	稳定性等待总超时时间；超时后会平稳降级
BROWSER_SNAPSHOT_MAX_NODES	100	每个快照的最大节点数
BROWSER_CONTEXT_TTL_SEC	600	空闲任务自动回收时间（秒）
BROWSER_STREAM_CHAR_CAP	16000	每个流缓冲区的最大字符数（超出时丢弃最旧内容，并添加分界标记）
BROWSER_STREAM_PAGE_CAP	64000	每个页面的流缓冲区字符总数
BROWSER_EVENT_MAX_ENTRIES	500	每个页面的最大事件数（控制台／异常／请求）；超出时丢弃最旧事件并增加计数器
BROWSER_EVENT_TEXT_CAP	500	每个事件文本的截断长度
BROWSER_EVENT_HANDLE_MAX	50	每个页面保留实时响应句柄的最近请求数（用于按需读取响应正文）
BROWSER_ALLOW_NETWORK_BODY	false	允许使用 browser_network_body（响应正文可能包含敏感数据）
BROWSER_NETWORK_BODY_CAP	4000	每个响应正文返回的最大字符数
BROWSER_TRANSPORT	stdio	stdio／http（适用于远程／多客户端的 streamable-http）
BROWSER_HTTP_HOST	127.0.0.1	HTTP 绑定地址；非 localhost 地址需要设置 BROWSER_HTTP_TOKEN（否则会拒绝启动）
BROWSER_HTTP_PORT	8817	HTTP 端口
BROWSER_HTTP_TOKEN	""	HTTP 传输的 Bearer 令牌
BROWSER_ALLOW_JS_EXECUTION	false	允许使用 browser_evaluate（启用后无条件触发 HITL）
BROWSER_HITL_RULES	[]	HITL 规则的 JSON 数组，例如 `[{"action":"click","name_pattern":"pay
BROWSER_AUDIT_PATH	~/.nexus-browser/audit.jsonl	审计日志路径
BROWSER_DIALOG_TIMEOUT_MS	20000	暂停的 confirm／prompt 自动关闭超时时间（操作记录会保留在事件日志中）
BROWSER_DOWNLOAD_DIR	~/.nexus-browser/downloads	保存已接受下载文件的位置（点击操作会报告文件名和路径）
BROWSER_PROXY	""	none = 使用 --no-proxy-server 启动浏览器（绕过系统代理）

工具

34 个工具：browser_navigate、browser_navigate_back、browser_snapshot、browser_click、browser_type、browser_hover、browser_press_key、browser_select_option、browser_upload_file（经 HITL 确认）、browser_drag、browser_dialog_respond（对话框会暂存，供 Agent/用户决定；接受操作要求 confirmed=true）、browser_adopt_page（在 cdp/persistent 模式下接管已打开的浏览器标签页；经 HITL 确认）、browser_read、browser_screenshot、browser_evaluate、browser_wait、browser_wait_stable、browser_wait_ms、browser_scroll、browser_scroll_to、browser_wait_navigation、browser_find（按文本定位内容 → refs）、browser_dismiss_popup、browser_list_pages、browser_switch_page、可观测性工具 browser_console、browser_errors、browser_network、browser_perf、browser_network_body，以及 4 个生命周期工具：browser_tasks、browser_close_task、browser_list_sessions、browser_close_session。

可观测性（调试）：每个页面从创建时起都会缓冲控制台输出、未捕获的异常和请求元数据；browser_errors() 会在一次调用中返回合并后的“JS 异常 + console.error + 失败请求”视图。这三项都支持 since 游标（省略 = 从上次读取的位置继续，0 = 全部）和 limit 分页。

性能：browser_perf() 会返回 FCP/LCP/CLS/INP、导航计时数据以及最慢的 5 个资源。可按需使用 browser_network_body(seq) 获取响应正文——默认关闭（BROWSER_ALLOW_NETWORK_BODY），每次调用都必须通过 confirmed=true 确认，设有硬性字符上限，且正文绝不会进入审计日志。

令牌成本：实测，而非宣称

相同的 10 步任务，两种服务均使用默认配置，在 JSON-RPC 载荷层进行计量（cl100k 令牌；测试框架和原始数据见 docs/bench/token-comparison.md，使用 bench/compare.py 复现）：

	nexus-browser-mcp	playwright-mcp
10 步任务总计	3,460 tok	26,032 tok
导航后立即获取快照	65 tok	6,931 tok

总体令牌用量减少 7.5 倍；重复获取快照时减少 100 倍——这是实际 Agent 循环中的主要成本（轮询、多步表单、状态确认）。

真实网站基准测试（7 个场景 × 每个场景 5–7 个可验证子任务：百度/Bing/DuckDuckGo 搜索、阅读 Wikipedia、Hacker News、浏览 GitHub — docs/bench/realworld.md）：子任务完成数为 37/42 对比 31/42，令牌用量为 18.2k 对比 566.4k（相差 31 倍），耗时为 107 秒对比 179 秒——仅一篇 Wikipedia 文章的快照就会让 pw-mcp 消耗约 252k 令牌，而 nexus 会限制内容长度并返回差异。企业任务套件（筛选/排序、读取仪表板、知识库问答、多步下单、价格比较 — docs/bench/enterprise-ops.md）：三种服务均为 21/21（对比 playwright-mcp 和 chrome-devtools-mcp）；令牌用量为 3.6k 对比 5.1k 对比 10.9k。在大规模测试中（106 个案例 / 184 个子任务，三种服务，使用带种子的确定性测试数据 — docs/bench/scale-ops.md）：完成数为 184/184 对比 180/184 对比 178/184；令牌用量为 153.5k 对比 180.5k 对比 231.1k（1.00 : 1.18 : 1.51）——竞争对手的差距稳定为零的地方是富文本 iframe 写入、下载可观测性和右键操作，而非随机误差。

在具有对抗性复杂布局的页面上进行元素识别（同名按钮网格、shadow DOM、iframe、隐藏/禁用陷阱、完整重新渲染 — docs/bench/element-acc.md）：nexus 为 92% = pw 为 92% < chrome-devtools-mcp 为 100%，且 cdt 的成本也最低——它对每个节点进行冗长的转储，其中包含轻量快照会省略的产品文本，而基于值的定位需要这些文本。我们将此作为文本裁剪的已知权衡公开：节省总令牌数毫无意义，除非每个精度百分点的成本也能维持，而这个测试套件就是预警指标（已对修复方案进行基准测试：仅在同名候选项冲突时附加同级文本摘要）。

HITL 确认可闭合操作循环：任何受保护的调用都会返回一次 CONFIRMATION_REQUIRED；用户在聊天中批准后，Agent 会使用 confirmed=true 重新调用（适用于 HITL 规则、browser_evaluate、browser_network_body）。

HTTP 传输（远程 / 多客户端）

默认使用 stdio（单个客户端）。如需远程或多客户端使用，请运行 streamable-HTTP 服务：

BROWSER_TRANSPORT=http BROWSER_HTTP_PORT=8817 nexus-browser-mcp

每个 MCP 会话都会获得独立的 session_id（与往常一样，每个任务使用隔离的上下文）。安全规则：若绑定到非 localhost 地址但未设置 BROWSER_HTTP_TOKEN，则拒绝启动——未经过身份验证的浏览器控制端口会带来安全隐患；设置令牌后，请求必须发送 Authorization: Bearer <token>。

流式内容（AI 回复等）：browser_read(wait_stable=true) 会等待 DOM 静止并在一次调用中读取全文；browser_read(selector=..., follow=true) 会增量跟踪，每次调用仅返回新内容（full=true 会返回整个缓冲区）。browser_wait_stable / browser_wait_ms 提供事件驱动和固定时长两种等待方式。

快照差异：如果重复调用 browser_snapshot 后的树与上一次逐节点完全相同（不包括 refs——Playwright 会在每次生成时重新编号），则返回约 120 个字符的 [no change] 提示，而非完整树；之前发出的 refs 会通过代际链保持有效；diff=false 会强制返回完整快照。任何实际变化（内容、框、属性）都会返回完整快照——不会进行部分合并，也不会显示过期视图。

大多数工具都接受可选的 task_id（默认为共享的 default 任务）。用法指南见 docs/（中文）。

开发

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 smoke

许可证

MIT