Stealth Agent Browser

stealth-agent-browser-mcp

一个模型上下文协议（MCP）服务，为 AI Agent 提供具备隐身级别的 Chromium 浏览器，并采用混合式辅助功能对象模型 + 标记集视觉界面。专为 Claude 构建，可与任何兼容 MCP 的宿主配合使用。

• 隐身优先。 使用 rebrowser-playwright 修补 Runtime.Enable CDP 泄漏，该泄漏可绕过 playwright-extra 类隐身插件。在常规 Playwright 失效的现代机器人检测套件（CreepJS、bot.sannysoft.com）中通过检测。
• 默认精简令牌用量。 browser_snapshot 返回 Playwright aria 快照 YAML（约 2–5 KB），而非原始 HTML（100 KB 以上）。每个交互元素都带有操作可直接使用的 [ref=eN] ID——无需选择器，也不会漂移。
• 在需要时启用混合视觉。 请求 mode: "hybrid"，服务就会在屏幕截图上叠加带编号的红框，帮助模型进行视觉定位（标记集提示，Yang 等人）。图像上的 ref ID 与 YAML 中的 ID 一致，无需担心两套编号不同步。
• 基于可读性的内容提取。 browser_scroll_read 通过 JSDOM 运行 Mozilla Readability，并返回整洁的 Markdown；也可仅返回增量，在内容未变时重新读取无需花费。
• 支持代理。 每个会话均可进行代理身份验证，适用于住宅代理池。

仅限授权用途。 隐身工具有正当用途（无障碍审计、自动化操作自己的账户、针对自有或获准测试的网站进行 QA）。请勿使用此服务违反网站服务条款或适用法律。请参阅 SECURITY.md。

---

安装

npm install -g stealth-agent-browser-mcp
# Chromium binary is fetched automatically on first launch
npx playwright-core install chromium

也可以通过 npx stealth-agent-browser-mcp 直接运行，无需安装。

快速开始（Claude Desktop / Claude Code / Cursor）

将以下内容添加到 MCP 配置中：

{
  "mcpServers": {
    "stealth-browser": {
      "command": "npx",
      "args": ["-y", "stealth-agent-browser-mcp"],
      "env": {
        "SAB_HEADLESS": "true",
        "SAB_STEALTH_LEVEL": "patched"
      }
    }
  }
}

重启宿主。Agent 就会看到下方列出的工具。

工具

工具	用途
browser_navigate	访问 URL 并返回快照。
browser_snapshot	aom（仅 YAML，成本最低）、vision（原始屏幕截图）或 hybrid（YAML + 标记集屏幕截图）。
browser_click	通过元素的 [ref=eN] ID 点击元素。
browser_type	通过 ref 在输入框/文本区域中输入内容。
browser_select	通过 ref 选择 <select> 中的选项。
browser_scroll_read	滚动并返回 Readability Markdown（默认仅返回增量）。
browser_wait_for	等待文本或 ref 变为可见。
browser_tabs	list / new / close / switch。
browser_eval	在页面的 MAIN 世界中计算 JS 表达式；返回 JSON 结果。
browser_set_proxy	更新单个代理配置（在 browser_restart 后生效）。
browser_set_proxy_pool	在运行时替换住宅代理池（在 browser_restart 后生效）。
browser_solve_captcha	备用验证码求解器（CapSolver / 2Captcha）。检测页面上的 Turnstile/hCaptcha/reCAPTCHA。
browser_restart	使用当前配置关闭并重新打开活动浏览器会话。

所有操作工具都通过最近一次 AOM 快照中提供的 ref 进行寻址。Ref 是 Playwright 自带的 aria-ref=eN ID——不存在第二套编号方案。

配置

全部通过环境变量配置：

变量	默认值	说明
SAB_HEADLESS	true	设为 false 可显示窗口（用于调试）。
SAB_STEALTH_LEVEL	patched	off | patched | paranoid。
SAB_PROXY_SERVER	—	单代理模式。例如：http://host:port
SAB_PROXY_USERNAME / SAB_PROXY_PASSWORD	—
SAB_PROXY_POOL	—	住宅代理池。使用逗号分隔的 URL（http://u:p@host:port,...），或包含 {server, username, password} 的 JSON 数组。
SAB_PROXY_ROTATION	per-restart	per-session | per-restart | static。
SAB_PROXY_STICKY_TEMPLATE	—	粘性 IP 服务商的用户名模板。${sessionId} 会进行插值。例如：brd-customer-c1-zone-res-session-${sessionId}。
SAB_HUMAN_MOUSE	true	使用贝塞尔路径点击，并在点击前稍作停顿。可防止 Datadome 进行轨迹分析。
SAB_CAPTCHA_PROVIDER	none	capsolver | twocaptcha | none。
SAB_CAPTCHA_API_KEY	—	服务商 API 密钥。
SAB_USER_DATA_DIR	—	持久化配置文件目录（Cookie 会积累信誉）。
SAB_DEFAULT_TIMEOUT_MS	15000	每项操作的超时时间。
SAB_MAX_ANNOTATED	75	混合模式下最多标注的方框数。
SAB_VIEWPORT_W / SAB_VIEWPORT_H	1366 / 768
SAB_LOCALE	en-US
SAB_TIMEZONE	America/New_York
LOG_LEVEL	info	debug、warn 等。始终写入 stderr。

架构

src/
├── index.ts         # Entry (stdio)
├── server.ts        # MCP server + tool registration
├── tools.ts         # Tool handlers
├── browser.ts       # Stealth Chromium launcher (rebrowser-playwright)
├── session.ts       # Per-connection browser/context/page state
├── snapshot.ts      # AOM + Set-of-Mark pipeline
├── annotate.ts      # SVG overlay compositing (sharp)
├── reader.ts        # Readability → Markdown (pierces open shadow roots)
├── fingerprint.ts   # Rotatable UA/viewport/timezone profiles
├── proxy.ts         # Residential pool + rotation + sticky-session template
├── human-mouse.ts   # Bezier-curve cursor paths (ghost-cursor math)
├── captcha.ts       # CapSolver / 2Captcha REST adapters
├── config.ts        # Zod-validated env config
└── logger.ts        # pino → stderr (never stdout)

所有日志都写入 stderr——stdout 专用于 JSON-RPC。切勿添加 console.log。

TLS / JA3 指纹——为何这里没有 Node 层的伪装器

爬虫常见的需求是：“通过 curl-impersonate 或 node-tls-client 伪装 TLS ClientHello（JA3），使其看起来像 Chrome。”

这适用于 Node 层的 HTTP 爬虫（fetch、got、axios）：TCP 连接由 Node 的 OpenSSL 发起，它发出的 ClientHello 签名与 Chrome 的 BoringSSL 不同，因此 Cloudflare / Akamai Bot Manager 会在网络层拦截请求，此时甚至还没有一个字节的 JavaScript 运行。

此 MCP 并非这种架构。 每个请求都通过 Chromium 发出。Chromium 的 TLS 堆栈就是 Chrome 的 TLS 堆栈（实际上使用相同的 BoringSSL 构建版本），因此 ClientHello JA3 从架构上来说就是 Chrome 的 JA3。无需也无法在 JS 层进行重写。

唯一仍可能暴露 TLS 信息的情况，是流量经过了会终止并重新发起 TLS 的代理（MITM）。住宅代理服务商（Bright Data、DataImpulse、Oxylabs residential、SOAX）在 TCP 层进行路由，不会对 TLS 进行 MITM，Chromium 握手会原样到达源站。确实会对 TLS 进行 MITM 的产品是托管式爬虫浏览器（Bright Data 的 Scraping Browser、Oxylabs Web Unblocker）；它们自带无头 Chrome，会取代此 MCP，而不是叠加在其上。

**总之：**使用 rebrowser-playwright + 住宅代理池（P1）+ 人类鼠标操作（P2），TLS 指纹、CDP 运行时、DOM 特征和行为层都与真实 Chrome 一致。验证码求解（P3）是后备方案，用于仍被标记的 1–5% 会话。

基准测试

npm run bench:stealth 会启动配置好的浏览器，访问公开的机器人检测测试页面（bot.sannysoft.com、CreepJS、pixelscan、BrowserLeaks WebRTC），并报告通过或失败。这些测试框架与 rebrowser-patches 和 Patchright 项目使用的相同——参考测试套件请参阅 rebrowser-bot-detector。

典型的本地测试运行结果（参见 test/）：

测试	结果
AOM YAML 包含所有交互元素的引用	✓
hybrid 模式返回 PNG + YAML，引用匹配	✓
按引用执行 click / type 后产生预期的 DOM 变化	✓
Readability 将文章提取为 Markdown	✓
重复滚动时，仅增量滚动返回 (no readable content change)	✓

对比

	stealth-agent-browser-mcp	playwright-mcp	browser-use MCP	computer use
CDP 级隐蔽性（Cloudflare/DataDome）	✓	✗	部分支持	✗
无障碍树快照	✓	✓	✓	✗
Set-of-Mark 视觉（带引用标签的截图）	✓	✗	✗	纯视觉
基于可读性的滚动与阅读	✓	✗	✗	✗
默认精简 Token	✓	✓	✗	✗
内置 Agent 循环	✗（由宿主的模型驱动）	✗	✓	✗

开发

npm install
npx playwright-core install chromium
npm run build
npm test

贡献

请参阅 CONTRIBUTING.md。所有贡献均采用 Apache-2.0 许可。

许可证

Apache-2.0