browser-persistent

一个带登录态的浏览器 MCP 服务：让 AI agent 用真实 Chrome 打开需要登录、或重度依赖 JavaScript 的页面。

面向的场景很具体：容器里没有显示器、没有 Playwright 自带浏览器、但你又需要 agent 读到「登录后才看得见」的内容。

它解决什么

常见的 headless 浏览器封装通常是一次性隔离档案——每次启动都是全新身份，没有登录态，很多页面只能拿到登录墙。本项目反过来：

1. 固定 profile，登录态跨进程留存，重启不重登；

2. headful 跑在 Xvfb 虚拟显示上（无显示器容器也能用），比纯 headless 更像真人环境；

3. 凭据只注入、不回显：从受保护文件读 cookie 注入浏览器，任何工具都不返回 cookie 的值；

4. 不下载浏览器：直接用系统 Chromium 配 playwright-core，省掉 Playwright 动辄 150MB 的浏览器下载（在国内网络环境里这步经常卡死）。

Related MCP server: CloakBrowser MCP

能力边界（实测，别信宣传）

诚实比功能重要，以下都是真机实测结论：

本项目不做验证码绕过，也不保证能绕过任何风控。 上面标 ❌ 和 ⚠️ 的，就是绕不过去，如实写明。

安装

# 系统依赖（Debian/Ubuntu）
apt-get install -y chromium xvfb

# 项目依赖
npm i playwright-core @modelcontextprotocol/sdk

配置

全部通过环境变量，都有默认值：

凭据文件的权限建议 600，且不要放进版本库（.gitignore 已排除）。

礼貌访问（三个护栏）

对着带风控的站点跑自动化，最容易被忽略的不是技术，是节奏。本项目内置三道护栏：

1. 域白名单：设了 DSH_BROWSER_ALLOW 之后，不在名单内的域名直接拒绝导航，连点击和填写也一并拒绝。

2. 最小间隔：DSH_BROWSER_MIN_INTERVAL_MS 控制两次导航的间隔，过快会直接报错并告知还需等待多久；单次可用 force: true 越过，但白名单与熔断不受影响。

3. 风控熔断：页面正文命中「访问频繁」「安全验证」「当前页面异常」「Just a moment」等特征后，自动熔断 30 分钟，期间所有导航被拒，browser_policy 可查剩余冷却时间。

三道护栏都不是绕过风控的技巧，而是在被风控之前先自己停手。实测中京东就是靠这一条把损失降到最低的。

接进 MCP 客户端

以支持 stdio MCP 的客户端为例：

{
  "mcpServers": {
    "browser-persistent": {
      "command": "node",
      "args": ["/path/to/browser-persistent/server.js"],
      "env": {
        "DSH_BROWSER_PROFILE": "/path/to/.browser-profile"
      }
    }
  }
}

工具一览

安全提醒

• profile 目录里等同于明文登录凭据，权限建议 700，永不入库、不外传。

• 一个长期稳定的 profile 意味着长期稳定的可识别身份，这本身是风险；用完即弃的隔离档案在隐私上更安全。取舍要自己想清楚。

• 只在你有权访问的账号与站点上使用。

关于定位

它不是通用反自动化方案，也不是「隐形浏览器」。它只做三件事：留登录态、在没有屏幕的地方跑 headful、省掉浏览器下载；外加三道让你别把账号玩坏的护栏。

License

MIT