Skip to main content
Glama
stealth-browser-mcp

stealth-browser-mcp

by lauyuen

stealth-browser-mcp

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

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

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

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


目录


Related MCP server: byob

工作原理

        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_navigate

url, waitUntil?

waitUntil 为 load、domcontentloaded、networkidle0、networkidle2(默认)之一。返回最终 URL、标题和 HTTP 状态码。

browser_click

selector

将元素滚动到视图中,然后将鼠标移动到元素内部的一个抖动点后再按下。

browser_type

selector, text, clearFirst?

以随机延迟逐字符输入。

browser_scroll

direction?, distance?

up 或 down,像素数(默认 600)。

browser_wait_for

selector?, milliseconds?

等待元素、休眠,或两者兼有。

读取页面

工具

参数

说明

browser_extract_text

selector?

去除脚本和样式;返回文本以及结构化的链接和表单字段。这是让模型读取页面的最经济方式。

browser_extract_html

selector?

原始 outerHTML。当你需要精确的标记或属性时使用。

browser_screenshot

fullPage?

以 MCP 图像内容的形式返回 PNG。

browser_evaluate

script

在页面上下文中运行 JavaScript 并返回结果。请参阅 SECURITY.md 中的警告。

会话与认证

工具

参数

说明

browser_autofill_login

service, account, usernameSelector?, passwordSelector, submitSelector?

从钥匙串读取密码并输入。密钥永远不会返回给模型。

keychain_store_credential

service, account, password

以 stealth-mcp:<service> 前缀写入钥匙串。推荐使用 CLI——见下文。

passkey_enable_virtual_authenticator

rpId?, account?

同时提供两个参数时,注入已存储的通行密钥。都不提供时,附加一个空的认证器,准备进行注册。

passkey_save_registration

rpId, account

捕获新注册的凭据并存储。

浏览器生命周期

工具

参数

说明

browser_status

—

连接状态、标签页数量、当前 URL、配置文件路径、是否附加了认证器。

browser_open_interactive_window

url?

在可见窗口中重新打开当前会话,以便你手动解决 CAPTCHA 或批准 2FA 提示,然后将控制权交回。

browser_close

—

优雅关闭并将 cookie 刷新到磁盘。

浏览器默认以无头模式启动,并在多次调用之间复用。 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。

变量

默认值

用途

BROWSER_PROFILE_DIR

~/.config/stealth-browser-mcp/profile

持久化 Chrome 配置文件。保存实时会话——请保持私密并远离版本控制。

CHROME_EXECUTABLE_PATH

平台默认值

要驱动的 Chrome 二进制文件。如果路径不存在,则回退到 Puppeteer 的 Chromium。

NAV_TIMEOUT

45000

导航和选择器超时时间,以毫秒为单位。

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

Available Tools

16 tools
browser_autofill_loginA

Automatically fill and submit a login form using credentials stored securely in macOS Keychain.

Inputs: account (required), service (required), passwordSelector (required), submitSelector, +1 more.

browser_clickA

Click an element on the page using human-like mouse movement and click delays.

Inputs: selector (required).

browser_closeA

Gracefully close the browser and flush session cookies/storage to disk.

Inputs: no named parameters.

browser_evaluateB

Execute a custom JavaScript expression in the active page context and return the result.

Inputs: script (required).

browser_extract_htmlC

Extract outer HTML of a specific element or the entire page DOM.

Inputs: selector.

browser_extract_textA

Extract cleaned text, links, and forms from the page for LLM reading.

Inputs: selector.

browser_navigateA

Navigate the stealth browser to a target URL with persistent authentication.

Inputs: url (required), waitUntil.

browser_open_interactive_windowA

Opens a non-headless visible Chrome window on the user desktop so the user can manually solve a CAPTCHA or complete 2FA.

Inputs: url.

browser_screenshotA

Capture a screenshot of the current page for visual inspection.

Inputs: fullPage.

browser_scrollB

Scroll the viewport up or down.

Inputs: distance, direction.

browser_statusB

Check the current status of the browser instance, active tabs, and persistent profile path.

Inputs: no named parameters.

browser_typeB

Type text into an input or textarea with realistic human keystroke timing delays.

Inputs: text (required), selector (required), clearFirst.

browser_wait_forB

Wait for a CSS selector to appear or sleep for a specified duration in milliseconds.

Inputs: selector, milliseconds.

keychain_store_credentialA

Store a username and password securely in macOS Keychain so the browser agent can log in automatically later.

Inputs: account (required), service (required), password (required).

passkey_enable_virtual_authenticatorC

Enables a Chrome DevTools Protocol (CDP) WebAuthn virtual authenticator and optionally injects a stored Passkey credential from Keychain.

Inputs: rpId, account.

passkey_save_registrationB

Captures newly registered Passkey credentials from the virtual authenticator and saves them to macOS Keychain for future automated logins.

Inputs: rpId (required), account (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 16 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: navigation, login, passkey management, keychain storage, clicking, typing, screenshotting, text extraction, HTML extraction, JS evaluation, scrolling, waiting, interactive window, status, and close. The overlap between extract_text and extract_html is minor and well-explained by their descriptions.

    Naming Consistency5/5

    Tool names follow a consistent pattern with functional prefixes (browser_, passkey_, keychain_) and descriptive verb_noun or verb_object combinations. All verbs are clear and consistently styled (snake_case), making the set predictable and scannable.

    Tool Count5/5

    16 tools is appropriate for a browser automation server covering navigation, interaction, authentication, extraction, and lifecycle management. Each tool earns its place and the count is neither sparse nor bloated for the intended scope.

    Completeness4/5

    The tool surface covers core browser automation workflows: navigation, login, passkey handling, interaction, content extraction, and browser lifecycle. Minor gaps exist such as explicit back/forward navigation or download handling, but these do not critically hinder typical automation tasks.

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables AI agents to authenticate with websites using a real Chromium browser with anti-detection measures and human-in-the-loop support for captchas and 2FA. Features stealth browsing, human-like interactions, and persistent session storage to automate and resume login workflows.
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Lets AI assistants control your real Chrome browser to perform web tasks like reading pages, taking screenshots, clicking, and typing, using your existing logged-in sessions.
      145
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI assistants and terminal users to control a logged-in Chrome browser, performing actions like opening pages, searching, filling forms, and taking screenshots without re-authentication.
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables AI agents to access authenticated websites by reusing your existing browser profile and cookies, so you never share passwords and sessions persist between runs.
      5
      5
      MIT