vibheksoni/stealth-browser-mcp · 上手攻略

仓库：vibheksoni/stealth-browser-mcp
链接：https://github.com/vibheksoni/stealth-browser-mcp
分类：MCP / 浏览器自动化
作者：Tom
更新：2026-08-15

是什么

stealth-browser-mcp 是一个基于 MCP（Model Context Protocol）的反检测浏览器自动化框架，核心目标是让 AI Agent 能够绕过反爬虫/反机器人机制（Cloudflare 挑战、登录墙、Queue-It 队列等）来控制真实 Chrome 内核浏览器。它由 nodriver（异步 Chrome DevTools Protocol 实现）、FastMCP 和 Chrome CDP 驱动，提供 97 个工具（Full 模式）或 20 个核心工具（Minimal 模式）。

作者实测可以穿透 Cloudflare 和 Queue-It 风格的挑战（⚠️ 效果因站点、地区、浏览器版本和检测器版本而异）。

解决什么问题

传统浏览器自动化框架（Playwright/Puppeteer/Selenium）面临的核心困境：

痛点	stealth-browser-mcp 解法
被 Cloudflare / hCaptcha 等反爬墙拦截	nodriver 模拟真实 Chrome 行为 + 反检测配置
AI Agent 不知道用什么工具	内置 Codex-style skill 引导工具选择顺序
需要像素级克隆 UI 元素	CDP 提取完整 CSS/DOM/事件/动画/资产
网络请求调试困难	内置 10 个网络监控工具，AI 可直接查询
工具太多不知道用哪些	Modular 加载：Full（97）/ Minimal（20）/ 自定义禁用
不同平台部署复杂	支持 Windows / macOS / Linux / Docker，自动检测浏览器

快速安装

环境要求

Python 3.10+
Chrome / Chromium / Microsoft Edge（任一，需可执行）
pip 或 uv

安装步骤

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

MCP 客户端配置

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"]}'

Claude Desktop（手动 JSON）

Windows (%APPDATA%\Claude\claude_desktop_config.json)：

{
  "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": {}
    }
  }
}

macOS / Linux (~/Library/Application Support/Claude/claude_desktop_config.json)：

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

FastMCP CLI（实验性）

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

核心用法

启动服务器

# 默认 Full 模式（97 工具）
python src/server.py

# Minimal 模式（20 核心工具）
python src/server.py --minimal

# 自定义禁用某些 section
python src/server.py --disable-cdp-functions --disable-dynamic-hooks

# 查看所有可用 section
python src/server.py --list-sections

# Debug 模式
python src/server.py --debug

# HTTP 传输（需设 auth token）
python src/server.py --transport http --host 127.0.0.1 --port 8000

启动后——让 AI Agent 使用

重启 MCP 客户端后，直接对 Agent 说：

Use stealth browser to navigate to https://example.com and take a screenshot.

Agent 会自动选择合适的工具。内置 skill 文件（skills/stealth-browser-mcp）会引导 Agent： - 推荐工具使用顺序 - 状态检查时机 - pre-document CDP script 使用方法 - 网络调试流程 - 浏览器清理规则

核心工具速查

浏览器管理

spawn_browser()           # 创建 stealth 浏览器实例
list_instances()          # 列出活跃会话
close_instance()          # 关闭浏览器
navigate(url="...")       # 导航到 URL

元素交互

query_elements(selector="css 或 xpath")   # 查找元素
click_element(element_id)                  # 点击
type_text(element_id, text)                # 模拟人类打字
paste_text(element_id, text)              # CDP 即时粘贴
take_screenshot()                          # 截图

网络调试

list_network_requests()           # 列出捕获的网络请求
get_request_details(request_id)   # 查看请求头/载荷
get_response_content(request_id)  # 读取响应体
search_network_requests(query)    # 搜索请求
modify_headers(...)               # 修改请求头

元素克隆（像素级 UI 复制）

clone_element_complete(element_id)     # 完整克隆（含 CSS/DOM/事件/动画/资产）
extract_element_styles(element_id)      # 提取 computed CSS
extract_element_structure(element_id)  # 提取 DOM 结构

Dynamic Hooks（AI 驱动的网络拦截）

# 可以拦截、阻止、重定向、满足或修改请求/响应流
# 受限 Python hooks，AI 引导生成

典型适用场景

AI Agent 网页操作：让 Agent 自主登录、填表、抓取需要 JS 渲染的页面
反检测数据采集：绕过 Cloudflare / hCaptcha / Imperva 等防护抓取公开数据
UI 克隆与还原：像素级提取元素样式和结构，用于 UI 重建或截图对比
网络调试与逆向：监控 AJAX 请求、分析 API 载荷、修改请求头调试接口
自动化测试：在真实浏览器环境（而非 headless 模拟）下做 E2E 测试
CI 流水线：Docker 化运行自动化测试，不依赖本地 Chrome 安装

坑与注意

反检测效果不保证：README 明确说"results vary by site, region, browser version, and detector version"——不能把它当成万能通行证，高级反爬系统（如 ByteDance / Google Account 级别）仍可能拦截
HTTP 传输安全：若启用 --transport http，必须设 STEALTH_BROWSER_MCP_AUTH_TOKEN，否则裸奔在网络上
Python 3.10+ 强制：3.9 及以下不兼容
文件上传白名单：file_upload() 只能从 BROWSER_FILE_UPLOAD_ALLOWED_DIRS 指定的目录读取，安全性设计合理但需提前配置
浏览器 idle 超时：BROWSER_IDLE_TIMEOUT 默认 600 秒自动关浏览器实例，长任务需调大
Windows 路径转义：JSON 配置中 Windows 路径需双反斜杠或用 raw string
XPool safe 模式：83 工具（禁用 Runtime.enable 触发的工具），可避免触发某些检测器
NodeMaven 赞助：README 底部有 NodeMaven 付费代理赞助，两行 discount code 是真实优惠但也属于付费推广内容

与同类对比

维度	stealth-browser-mcp	Playwright MCP	Puppeteer	Selenium
反检测	✅ 专用设计	❌	❌	❌
MCP 协议	✅ 原生	✅	❌	❌
工具数量	97（Full）/20（Minimal）	中等	少	多
AI Agent 集成	✅ 内置 skill	需要自行接入	❌	❌
网络拦截/Hook	✅ Dynamic Hooks	部分	❌	❌
像素级 UI 克隆	✅	❌	❌	❌
语言	Python	多语言	JavaScript	多语言
安装复杂度	中（需配 MCP 客户端）	低	低	低

⚠️ stealth-browser-mcp 核心差异化是反检测 + AI Agent 集成，而非通用浏览器自动化；简单场景用 Playwright 更轻量。

一句话推荐结论

stealth-browser-mcp 是目前 MCP 生态中唯一专门为 AI Agent 反检测浏览器自动化设计的工具链——如果你需要让 AI Agent 真正控制一个有真实浏览指纹的浏览器、绕过 Cloudflare 挑战、抓取 JS 渲染页面，它是目前最完整的方案；但高级反爬系统仍可能拦截，且 97 工具的学习曲线不低，先用 Minimal 模式跑通核心流程再扩展。

🤖 Agent skill 路径：skills/stealth-browser-mcp（Codex-style 引导） 🐛 Issue / 功能请求：https://github.com/vibheksoni/stealth-browser-mcp/issues