nexus-browser-mcp

事件驱动确定性快照的浏览器操控 MCP 服务器。

基于 Playwright,通过 Accessibility Tree(无障碍树)让 LLM 驱动浏览器——导航、点击、输入、读取、表单、多标签。与市面同类产品(Playwright MCP 等)的核心差异:

1. 确定性快照:不靠固定间隔 sleep 硬等,而是注入 MutationObserver 记录最后一次 DOM 变异,由浏览器自身的 requestAnimationFrame 循环判定"页面已静默 STABLE_WINDOW_MS(默认 800ms)"后才提取快照。杜绝"快照抓在动画/加载中"的竞态。
2. 内嵌治理门:HITL 规则(如点击"支付/确认"需人工)、browser_evaluate 默认禁用+无条件确认、JSONL 审计(含敏感参数脱敏)。
3. 多 task 隔离:一个 MCP 连接(session)内可建多个独立 task_id,各自独立 BrowserContext(登录态互不污染),TTL 空闲回收、回收后再次使用时自动重建并恢复上次页面。
4. 死亡可观测 + 自愈:标签页/浏览器被外部关闭或崩溃后,下次调用自动重建(持久化 profile 登录态不丢),并在工具返回前置 [状态变更] 通知,明确告知"恢复了什么、丢了什么",不再泄漏 Playwright 底层异常。

安装

pip install nexus-browser-mcp
# 或
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 默认 transport:

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

详细见 docs/INTEGRATE.md。

使用你自己的浏览器(带登录态)

默认 isolated 模式启动 Playwright 内置 Chromium,不带你的 cookie/登录态。要用你自己的浏览器,二选一:

方式 A — 直接加载你的浏览器 profile(推荐,最省事)

用系统 Chrome 加载你平时的用户数据目录(Cookie/登录态/书签都在):

BROWSER_CHANNEL=chrome
BROWSER_USER_DATA_DIR="C:\Users\你的用户名\AppData\Local\Google\Chrome\User Data"

注意:用自己的 User Data 时,进程会占用浏览器,期间你自己开 Chrome 会冲突。建议复制一份 profile 或用独立的 --user-data-dir 指向一个专用目录。

推荐做法:工具专用 profile(不与日常浏览器冲突)

用 BROWSER_CHANNEL=chrome + 指向一个专用 user data 目录(如 C:\Users\<你>\.nexus-browser\chrome-profile):

BROWSER_CHANNEL=chrome
BROWSER_USER_DATA_DIR="C:\Users\你的用户名\.nexus-browser\chrome-profile"

首次使用需要在 agent 调浏览器工具时弹出的专用 Chrome 里登录一次目标网站,之后 cookie 永久保存在该 profile,agent 从此自带登录态;且与你日常浏览器完全隔离,互不干扰。

方式 B — CDP 连接运行中的 Chrome

先启动: chrome --remote-debugging-port=9222,然后 BROWSER_MODE=cdp。

若 CDP 连接失败,服务器现在会明确报错(不再静默启动全新浏览器),提示你先启动调试端口浏览器。

配置(环境变量)

所有可选项通过 BROWSER_ 前缀环境变量覆盖:

工具

20 个工具:browser_navigate、browser_snapshot、browser_click、browser_type、browser_read、browser_screenshot、browser_evaluate、browser_wait、browser_wait_stable、browser_wait_ms、browser_scroll、browser_scroll_to、browser_wait_navigation、browser_dismiss_popup、browser_list_pages、browser_switch_page 及 4 个生命周期工具 browser_tasks、browser_close_task、browser_list_sessions、browser_close_session。

流式内容(AI 回复等):browser_read(wait_stable=true) 等 DOM 静默后一次读全;browser_read(selector=..., follow=true) 增量跟踪,每次只回新增部分,full=true 取缓冲全文。browser_wait_stable / browser_wait_ms 提供事件驱动等待与纯等待两种原语。

多数工具接受可选 task_id(不传则用默认 task)。见 docs/ 中的用法指南。

开发

uv venv
uv pip install -e ".[dev]"
python -m pytest tests -q
ruff check src tests
python -m smokes.test_e2e           # 真实浏览器冒烟
python -m smokes.test_e2e_interact  # 表单 + 多 task 冒烟

License

MIT