stealth-browser-mcp

一个 MCP 服务器，为 AI 助手提供一个保持登录状态的真实 Chrome 浏览器。

大多数浏览器自动化工具交给模型的是一个全新的空浏览器。而本工具驱动的是一个持久的 Chrome 配置文件，因此一旦你亲自登录过某个网站——无论它要求的是 2FA、CAPTCHA 还是设备审批——模型就能在后续运行中继续使用该会话，而永远不会看到你的密码。

对于无法容忍脚本化登录的网站，它提供了两个逃生通道：在填写时从 macOS 钥匙串 中提取凭据，以及通过 Chrome 的虚拟认证器重放 WebAuthn 通行密钥。

[!WARNING] 这是一个强力工具。它让语言模型控制一个保存着你实时会话的浏览器，并且它能够将你存储的密码输入到模型所选择的页面中。在将它指向任何你在意的东西之前，请阅读 SECURITY.md 和 负责任使用。

目录

• 工作原理

• 环境要求

• 安装

• 连接到 MCP 客户端

• 首次登录

• 工具参考

• 在钥匙串中存储凭据

• 通行密钥

• 配置

• 验证隐身效果

• 故障排除

• 负责任使用

• 许可证

Related MCP server: agent-browser-mcp

工作原理

        MCP client (Claude Code, Claude Desktop, Cursor, …)
                          │
                          │  JSON-RPC over stdio
                          ▼
              ┌───────────────────────────┐
              │   stealth-browser-mcp     │
              │   16 tools, one browser   │
              └─────┬───────────────┬─────┘
                    │               │
     credentials    │               │   CDP + Puppeteer
                    ▼               ▼
        ┌───────────────────┐   ┌───────────────────────┐
        │  macOS Keychain   │   │  Google Chrome        │
        │  stealth-mcp:*    │   │  + stealth plugin     │
        │  passwords,       │   │  + WebAuthn virtual   │
        │  passkey material │   │    authenticator      │
        └───────────────────┘   └───────────┬───────────┘
                                            │
                                            ▼
                              ┌─────────────────────────┐
                              │  Persistent profile dir │
                              │  cookies · localStorage │
                              │  IndexedDB · sessions   │
                              └─────────────────────────┘

三个部分协同工作：

持久化。 Chrome 针对固定的 userDataDir 启动，而不是一次性的临时目录。交互式登录一次，cookie 就能在之后的所有运行中保留——自动化在真实网站上失效的常见原因就此消失。

隐身。 puppeteer-extra-plugin-stealth 修补了众所周知的自动化特征，服务器还在此基础上叠加了更多措施：navigator.webdriver 为 undefined，window.chrome.runtime 存在，用户代理中移除了 HeadlessChrome，并设置了 --disable-blink-features=AutomationControlled。点击时鼠标会沿路径移动到目标内部的一个抖动点；输入则逐字符进行，间隔 30–100 毫秒。

会话复用而非会话创建。 设计目标是完全避免自动化登录。钥匙串自动填充和通行密钥重放仅用于你无法避免登录的情况。

环境要求

• Node.js 18 或更高版本

• Google Chrome。 Puppeteer 自带的 Chromium 也可以使用，但真正的 Chrome 构建版本明显更不易被检测。

• macOS，如果你需要钥匙串和通行密钥功能。其他所有功能——导航、提取、截图、持久化配置文件——均跨平台。钥匙串层会调用 /usr/bin/security，在其他平台上会失败；浏览器工具不会触碰它。

安装

git clone https://github.com/lauyuen/stealth-browser-mcp.git
cd stealth-browser-mcp
npm install

可选：复制示例环境文件并编辑它：

cp .env.example .env

确认浏览器能够启动且规避措施已生效：

npm run check-stealth

连接到 MCP 客户端

服务器通过 stdio 通信。使用绝对路径将你的客户端指向 src/server.js。

Claude Code

claude mcp add stealth-browser -- node /absolute/path/to/stealth-browser-mcp/src/server.js

Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "stealth-browser": {
      "command": "node",
      "args": ["/absolute/path/to/stealth-browser-mcp/src/server.js"]
    }
  }
}

任何其他 MCP 客户端 — 结构相同，外加可选的配置文件覆盖：

{
  "mcpServers": {
    "stealth-browser": {
      "command": "node",
      "args": ["/absolute/path/to/stealth-browser-mcp/src/server.js"],
      "env": {
        "BROWSER_PROFILE_DIR": "/absolute/path/to/a/private/profile/dir"
      }
    }
  }
}

之后重启客户端。browser_status 是确认连接已建立的最快方式。

首次登录

在模型可以使用某个网站之前，先自行填充配置文件：

npm run login -- https://example.com

一个可见的 Chrome 窗口会打开，使用与 MCP 服务器相同的配置文件。正常登录——密码管理器、2FA 提示、CAPTCHA、"记住此设备"，全部照常。完成后在终端中按 Enter，会话即被刷新到磁盘。

之后每次 MCP 运行都会继承该会话。每个网站重复此操作。会话按网站自身的时间表过期，因此当网站将你登出时，请重新运行此操作。

工具参考

导航与交互

读取页面

会话与认证

浏览器生命周期

浏览器默认以无头模式启动，并在多次调用之间复用。 browser_open_interactive_window 是唯一一个将其切换为可见窗口的工具。

在钥匙串中存储凭据

密码存放在 macOS 钥匙串中，使用 stealth-mcp: 服务前缀——绝不会存放在本仓库的任何文件中，也绝不会出现在模型的上下文中。

npm run keychain set github you@example.com     # prompts; input is not echoed
npm run keychain get github you@example.com     # confirms presence, prints length only
npm run keychain delete github you@example.com

然后模型触发登录，而永远不会得知密钥：

// browser_autofill_login
{
  "service": "github",
  "account": "you@example.com",
  "usernameSelector": "#login_field",
  "passwordSelector": "#password",
  "submitSelector": "input[type='submit']"
}

service 是你选择的任意标签——只需在 CLI 和工具调用之间保持一致即可。

你也可以将密码作为尾随 CLI 参数传入以用于脚本化，但它会出现在你的 shell 历史和进程列表中，因此命令会在你这样做时发出警告。

通行密钥

Chrome 通过 DevTools 协议暴露了一个 WebAuthn 虚拟认证器——一个用于测试 WebAuthn 流程的软件认证器。本服务器驱动它，并将生成的密钥材料持久化在钥匙串中，使其在多次运行之间得以保留。

注册自动化通行密钥

1. 不带参数调用 passkey_enable_virtual_authenticator。

2. 导航到网站的"添加通行密钥"流程并完成它。虚拟认证器会应答挑战；不会出现操作系统提示。

3. 使用网站的 rpId 和你的账户调用 passkey_save_registration。

之后使用

使用 rpId 和 account 调用 passkey_enable_virtual_authenticator，在导航之前注入已存储的凭据，网站就会在无提示的情况下让你登录。

[!CAUTION] 以这种方式持有的通行密钥是一个文件，而不是硬件密钥。它可以被复制，而这正是真实通行密钥存在所要防止的属性。请仅用它注册仅限自动化的通行密钥。不要用它来保护你的邮箱、银行或任何其他丢失会造成严重后果的东西。

配置

所有设置均为环境变量，从进程环境或 .env 文件中读取。参见 .env.example。

Chrome 启动标志和默认的 1280×800 视口位于 src/config.js 中。有几个标志以安全性换取兼容性——SECURITY.md 解释了是哪些以及为什么你可能想要移除它们。

验证隐身效果

npm run check-stealth

该工具会报告 navigator.webdriver、window.chrome、window.chrome.runtime、插件数量、navigator.languages 以及有效的用户代理，然后打印解析出的配置文件和 Chrome 路径。

如需更严格的检测，可将浏览器指向指纹识别页面——例如 bot.sannysoft.com 或 abrahamjuliot.github.io/creepjs——先调用 browser_navigate，再调用 browser_screenshot。

没有任何隐身方案是绝对无法检测的。防护严密的网站会将指纹识别与行为分析、IP 信誉和账号历史相结合，仍然能够识别自动化操作。请将此视为"不会触发明显的检测项"，而非"完全隐形"。

故障排查

"无法启动浏览器进程"/配置文件被锁定。 Chrome 每个配置文件目录只允许一个进程。请关闭你手动针对同一目录启动的任何 Chrome。服务器在启动时会清除过期的 Singleton* 锁文件，并会通过 DevTools 端口重新连接到活动实例，但正在运行且占用该配置文件的 Chrome 会优先。

某个网站将模型登出或阻止了它。 存储的会话已过期。重新运行 npm run login -- <url>。

选择器不匹配。 在窄范围选择器上调用 browser_extract_html，让模型读取真实标记而不是猜测。单页应用通常较晚挂载输入框——先调用 browser_wait_for。

出现 CAPTCHA。 调用 browser_open_interactive_window，自行解决，然后继续。解决状态会保留在配置文件中。

Linux 或 Windows 上出现钥匙串错误。 这是预期行为——该层仅适用于 macOS。浏览器工具在所有平台上均可使用；凭据和通行密钥工具则不可用。

负责任的使用

本项目存在的意义是让助手能够在你已经拥有账号的网站上操作，使用你自己建立的会话。这就是预期的适用范围，持久化配置文件的设计也体现了这一点。

反检测和凭据自动化显然可以被用于其他目的。在针对某个网站运行之前，请考虑：

• 网站的条款。 许多网站明确禁止自动化访问。绕过机器人防御可能违反你已同意的合同，在某些司法管辖区，未经授权的访问还涉及刑事责任。能够绕过某项控制并不等于被授权这样做。

• 同意。 自动化操作属于你自己的账号，或你已获得书面授权代为操作的账号。他人凭据出现在你的钥匙串中并不等于获得同意。

• 负载。 自行限制请求频率。在适用的情况下遵守 robots.txt。给网站造成实际经济损失的自动化行为，是让这项技术被所有人封禁的捷径。

• 他人的数据。 模型读取的页面会流入你的 MCP 客户端提供商。请勿将第三方的个人信息经由它传输。

主要目的是破解特定网站防护、窃取凭据或扩大滥用的贡献将不会被合并。

许可证

MIT © Yuen Lau