Stealth Browser Mcp

Stealth Browser MCP

为兼容 MCP 的 AI Agent 提供隐身浏览器自动化。

借助由 nodriver、Chrome DevTools Protocol 和 FastMCP 驱动的真实 Chrome 系浏览器实例，应对 Cloudflare 验证、反机器人检查和登录墙。

赞助商

NodeMaven — 为网页抓取和自动化提供最高效的代理服务商，拥有市场上质量最高的 IP。

为什么选择 NodeMaven？

• ZIP 码定位
• 99.9% 正常运行时间
• IP 筛选：所有代理的欺诈评分均 <97%
• 无需 KYC
• 独特的免费工具：代理带宽检查器、Meta Tag Checker、IP Lookup 等！

Stealth-browser-mcp 用户专享优惠码

• STEALTHMCP35 — 移动和住宅代理优惠 35%
• STEALTHMCP40 — ISP（静态）代理优惠 40%

开始使用 NodeMaven

赞助商展示位。NodeMaven 是本项目的付费赞助商。

目录

• 赞助商
• 演示
• 功能
• 快速入门
• Agent 技能
• 信任模型
• 模块化架构
• 服务配置
• 工具箱
• 隐身浏览器与 Playwright MCP 对比
• 故障排除
• 示例
• 展示
• 路线图
• 贡献
• 支持
• 许可证

演示

Stealth Browser MCP 通过 AI 聊天指令通过 Cloudflare 验证、克隆 UI 元素并检查网络流量。

功能

• 抗机器人检测 - 测试中已通过 Cloudflare 和 Queue-It 风格的挑战；实际效果因网站、地区、浏览器版本和检测器版本而异。
• 11 个分类，共 101 个工具 - 涵盖基础导航到高级 CDP 函数执行。
• 模块化加载 - 可运行完整的 101 个工具，或精简的 21 个核心工具；禁用不需要的分类。
• 像素级精准的元素克隆 - 通过 CDP 提取包含 CSS、DOM 结构、事件、动画和资源的完整元素。
• 网络检查 - 通过 AI Agent 检查请求、响应、标头、负载和捕获的正文。
• 动态钩子系统 - 受限的 Python 钩子可拦截、阻止、重定向、处理或修改请求/响应流。
• CDP 执行 - 通过受信任的本地 MCP 客户端运行 JavaScript、直接 CDP 命令和文档加载前脚本。
• 即时文本输入 - 通过 CDP 粘贴大量内容、模拟真人按键输入，或使用受信任的 CDP 按键事件按下真实按键。
• 跨平台 - 支持 Windows、macOS、Linux、Docker 和 CI 环境，并可自动检测浏览器和平台。
• 浏览器支持 - 支持 Chrome、Chromium 和 Microsoft Edge，并可自动查找可执行文件。
• 简洁的 MCP 集成 - 通过标准 MCP 客户端运行，无需自定义代理。

快速开始

1. 安装

需要 Python 3.10+，以及 Chrome、Chromium 或 Microsoft Edge。

使用 pipx（推荐）：

pipx install browserstealthmcp

这会在你的 PATH 中添加 stealth-browser-mcp 命令。使用 pipx upgrade browserstealthmcp 升级。uvx browserstealthmcp 无需安装即可运行。若要运行最新提交而不是正式版本，请使用 pipx install git+https://github.com/vibheksoni/stealth-browser-mcp.git。

该 PyPI 软件包名为 browserstealthmcp，因为 PyPI 上的 stealth-browser-mcp 属于另一个无关项目。运行 pipx install stealth-browser-mcp 安装的是那个项目，而不是本项目。

从克隆的仓库安装（用于开发）：

git clone https://github.com/vibheksoni/stealth-browser-mcp.git
cd stealth-browser-mcp
python -m venv venv

# Windows
venv\Scripts\activate

# macOS / Linux
source venv/bin/activate

pip install -r requirements.txt

2. 添加到 MCP 客户端

使用 pipx 安装：

claude mcp add stealth-browser-mcp -- stealth-browser-mcp

或者，在任何客户端的 JSON 配置中添加：

{
  "mcpServers": {
    "stealth-browser-mcp": {
      "command": "stealth-browser-mcp",
      "args": [],
      "env": {}
    }
  }
}

如果客户端找不到该命令，请使用 pipx list 显示的完整路径。使用 uv 时，可以跳过安装并使用 "command": "uvx", "args": ["browserstealthmcp"]。

从克隆的仓库安装，并使用 Claude Code CLI：

Windows：

claude mcp add-json stealth-browser-mcp "{\"type\":\"stdio\",\"command\":\"C:\\path\\to\\stealth-browser-mcp\\venv\\Scripts\\python.exe\",\"args\":[\"C:\\path\\to\\stealth-browser-mcp\\src\\server.py\"]}"

macOS / Linux：

claude mcp add-json stealth-browser-mcp '{
  "type": "stdio",
  "command": "/path/to/stealth-browser-mcp/venv/bin/python",
  "args": ["/path/to/stealth-browser-mcp/src/server.py"]
}'

将示例路径替换为你实际克隆仓库的路径。

{
  "mcpServers": {
    "stealth-browser-mcp": {
      "command": "C:\\path\\to\\stealth-browser-mcp\\venv\\Scripts\\python.exe",
      "args": ["C:\\path\\to\\stealth-browser-mcp\\src\\server.py"],
      "env": {}
    }
  }
}

{
  "mcpServers": {
    "stealth-browser-mcp": {
      "command": "/path/to/stealth-browser-mcp/venv/bin/python",
      "args": ["/path/to/stealth-browser-mcp/src/server.py"],
      "env": {}
    }
  }
}

pip install fastmcp
fastmcp install claude-desktop src/server.py --with-requirements requirements.txt
fastmcp install claude-code src/server.py --with-requirements requirements.txt
fastmcp install cursor src/server.py --with-requirements requirements.txt

3. 测试

重启 MCP 客户端，并向 Agent 提出请求：

使用 stealth-browser 导航到 https://example.com 并截取屏幕截图。

Agent 技能

此仓库包含一个 Agent 技能，位于 skills/stealth-browser-mcp，适用于支持 Codex 风格技能的客户端。它会指导 Agent 按照推荐顺序使用工具、检查状态、使用文档加载前 CDP 脚本、排查网络问题，并遵循浏览器清理规则。

如果大模型难以选择合适的 MCP 工具，或在执行操作后忘记验证浏览器状态，请使用此技能。如果客户端不会自动加载仓库本地的技能，请将 skills/stealth-browser-mcp 添加到客户端技能目录，或在该目录中创建指向它的符号链接。

信任模型

此服务提供强大的本地浏览器控制原语：CDP 执行、页面 JavaScript 执行、Cookie／存储访问、网络拦截、动态钩子、标头修改、导航，以及从允许列表中的本地路径上传文件。

请将 MCP 客户端或 Agent 视为安全主体。推荐的部署方式是使用可信的桌面 MCP 客户端，通过本地 stdio 传输运行。如果使用 HTTP 传输，请设置 STEALTH_BROWSER_MCP_AUTH_TOKEN，并且不要在受信任的本地网络或专用网络之外暴露未经身份验证的 HTTP 服务。

模块化架构

按需选择所需功能。运行完整的 101 工具套件，或精简为包含 21 个工具的核心版本。

stealth-browser-mcp --minimal
stealth-browser-mcp --disable-cdp-functions --disable-dynamic-hooks
stealth-browser-mcp --list-sections
stealth-browser-mcp --debug
stealth-browser-mcp --transport http --host 127.0.0.1 --port 8000

从克隆的项目运行时，python src/server.py 接受相同的标志。

使用 --debug 或设置 STEALTH_BROWSER_DEBUG=1，即可在 stderr 上启用详细的服务诊断信息。默认情况下，正常的 MCP stdio 运行保持静默，以避免破坏 JSON-RPC 传输输出。

可用功能分区：

服务端配置

以下是 MCP 服务进程的环境变量。可在 shell、服务管理器、Docker 环境或 MCP 客户端的 env 块中设置。

PowerShell 示例：

$env:STEALTH_BROWSER_MCP_AUTH_TOKEN='replace-with-a-long-random-token'
$env:BROWSER_IDLE_TIMEOUT='900'
$env:BROWSER_IDLE_REAPER_INTERVAL='30'
$env:BROWSER_ORPHAN_PROFILE_MAX_AGE='43200'
$env:BROWSER_FILE_UPLOAD_ALLOWED_DIRS='C:\Users\me\uploads;C:\Users\me\Documents'
python src/server.py

MCP 客户端的 env 块：

{
  "mcpServers": {
    "stealth-browser-mcp": {
      "command": "C:\\path\\to\\stealth-browser-mcp\\venv\\Scripts\\python.exe",
      "args": ["C:\\path\\to\\stealth-browser-mcp\\src\\server.py"],
      "env": {
        "STEALTH_BROWSER_MCP_AUTH_TOKEN": "replace-with-a-long-random-token",
        "BROWSER_IDLE_TIMEOUT": "900",
        "BROWSER_FILE_UPLOAD_ALLOWED_DIRS": "C:\\Users\\me\\uploads;C:\\Users\\me\\Documents"
      }
    }
  }
}

HTTP 客户端示例：

from fastmcp import Client
from fastmcp.client.auth import BearerAuth

client = Client(
    "http://127.0.0.1:8000/mcp/",
    auth=BearerAuth("replace-with-a-long-random-token"),
)

单实例闲置超时覆盖：

• spawn_browser(idle_timeout_seconds=1800) 会让该实例在闲置 30 分钟后关闭。
• spawn_browser(idle_timeout_seconds=0) 会为该实例禁用闲置回收。

工具箱

Stealth 与 Playwright MCP

检测结果反映特定时点的情况，并取决于网站策略、地区、浏览器版本、IP 信誉度和检测器版本。请参阅 STEALTH_TESTS.md，了解 benchmarks/stealth/ 基准测试的每周自动化结果。该测试通过 GitHub Actions 在 Linux、Windows 和 macOS 上运行，并提供较早的手动测试快照。

故障排查

找不到兼容的浏览器 安装 Chrome、Chromium 或 Microsoft Edge。服务会自动检测第一个可用的浏览器。运行 validate_browser_environment_tool() 进行诊断。

工具挂起或返回格式错误的 JSON 在 MCP stdio 传输期间，调试输出不得打印到 stdout。拉取最新的 master 分支；除非正在诊断问题，否则请关闭调试日志。

需要详细诊断信息，但不想让常规运行产生过多输出 使用 python src/server.py --debug 或设置 STEALTH_BROWSER_DEBUG=1。调试日志会输出到 stderr；默认情况下，常规 MCP stdio 运行不会产生输出。

浏览器在 Linux、Docker 或 CI 上崩溃 仅当环境有此要求时，才使用 --sandbox=false；或者确保环境支持 Chromium 沙盒。服务会自动检测 root/容器环境并调整启动参数。

孤立的 Chromium 进程或 uc_* 临时配置文件不断累积 服务会自动回收空闲的浏览器实例，并在启动时清理已跟踪的孤立浏览器进程和过期的 uc_* 临时配置文件。只有在希望完全手动管理浏览器生命周期时，才设置 BROWSER_IDLE_TIMEOUT=0。

macOS 磁盘被 code_sign_clone 文件夹占满 旧版本会让 Chrome 在每次启动时将其应用程序包复制到 com.google.Chrome.code_sign_clone，而实例崩溃或被终止后，这些副本仍会残留。现在，服务会关闭 MacAppCodeSignClone 并启动 Chrome，因此不会再生成新副本。若要删除旧版本遗留的副本，请退出 Chrome 并运行 rm -rf /private/var/folders/*/*/X/com.google.Chrome.code_sign_clone（Edge 请使用 com.microsoft.edgemac.code_sign_clone）。

工具太多，导致 AI 聊天界面杂乱 使用 --minimal 获取 20 个核心工具，使用 --xpool-safe 以兼容 xpool 的模式运行，或选择性地禁用各个部分：

python src/server.py --disable-cdp-functions --disable-dynamic-hooks --disable-progressive-cloning

出现找不到模块的错误 请确保已激活虚拟环境并安装依赖：

pip install -r requirements.txt

示例

• 市场调研 - 提取竞争对手的定价和功能，然后输出对比表。
• UI 克隆 - 使用完全一致的字体、样式、资源和交互，重建定价版块。
• 库存监控 - 监控产品页面，并在库存发生变化时发送提醒。
• API 逆向工程 - 拦截请求、梳理端点并检查数据流。
• 表单自动化 - 上传来自允许路径的文件，并验证页面的最终状态。

所有操作均由单次 AI Agent 对话驱动。

展示

Augment Code 首页主视觉复刻 - 一位用户请 Claude 复刻 augmentcode.com 的主视觉区域。Agent 启动了一个隐身浏览器，访问该网站，通过 CDP 提取完整元素（样式、结构、素材），并生成了一个像素级精准的 HTML 复刻页面，支持响应式设计和动画。整个过程在不到两分钟的对话中完成。

查看复刻页面 | 完整演示

路线图

请参阅 ROADMAP.md 中的实时计划。欢迎贡献。

贡献

阅读 CONTRIBUTING.md 并提交 PR。欢迎首次贡献者。

如果这个项目为你节省了时间，请为仓库点个星。这比你想象的更有帮助。

支持

如果这个工具为你节省了时间或帮你赚了钱，可以考虑支持项目开发：

• 请我喝杯咖啡

许可证

MIT - 详见 LICENSE。