内容
<p align="center">
<img src="assets/logo.svg" alt="无驱动浏览器自动化MCP服务器 — 不被检测的浏览器自动化" width="130" height="130">
</p>
# 无驱动浏览器自动化MCP服务器
**不被检测、抗机器人的浏览器自动化MCP服务器** — 为 **Claude**、**Claude Code**、**Cursor**、**Windsurf** 等AI代理和任何 [模型上下文协议](https://modelcontextprotocol.io) 客户端提供的无缝、隐身替代方案 [`chrome-devtools-mcp`](https://github.com/ChromeDevTools/chrome-devtools-mcp)。由 [nodriver](https://github.com/ultrafunkamsterdam/nodriver) 驱动，您的代理可以浏览、抓取和自动化真正的Chrome **而不会触发Cloudflare、hCaptcha或WebDriver指纹检测**。
> **关键词：** MCP服务器 · 浏览器自动化 · 不被检测的chromedriver · 抗机器人 · Cloudflare绕过 · 网络抓取 · Claude · Cursor · nodriver · chrome-devtools-mcp替代品 · Playwright/Puppeteer替代品 · AI代理工具。
## 为什么选择它？
`chrome-devtools-mcp` 和大多数基于Playwright/Puppeteer的服务器通过CDP/WebDriver驱动Chrome，这种方式会留下可检测的指纹（`navigator.webdriver`，CDP工件）。反机器人系统（Cloudflare，hCaptcha，DataDome等）立即标记这些。
`nodriver` 是 `undetected-chromedriver` 的继任者。它 **直接与CDP协议通信** — 没有ChromeDriver二进制文件，没有Selenium/WebDriver标记 — 因此自动化会话看起来像一个真实用户。该服务器通过 **与`chrome-devtools-mcp`相同的工具表面** （56个工具）公开其功能，因此您的代理获得了一个熟悉的API，具有更好的隐身功能。
## 功能
- 🕵️ **设计不被检测** — `navigator.webdriver` 为 `undefined`，无CDP指纹。
- ☁️ **内置Cloudflare挑战解决器** (`cf_verify`)。
- 🧩 **56个工具**，涵盖导航、输入、快照、截图、内容/PDF导出、网络 + 控制台检查、设备模拟、cookie/存储、会话、配置文件和性能跟踪。
- 📄 **可访问性树快照** (`take_snapshot`) — 可搜索、LLM友好的页面文本，比截图小得多、快得多。
- 📱 **设备模拟** （Pixel 7，iPad）带有正确的UA / 客户端提示。
- 💾 **会话保存/恢复** — 在运行之间持久化登录。
- 🧬 **默认情况下是短暂的，可以同时运行多个实例** — 每个会话都有自己的临时Chrome配置文件（自动删除），因此Claude Desktop、Claude Code和VS Code可以 **同时驱动nodriver而不会发生冲突**。按需提供 **持久配置文件** 以重用登录。
- ⚡ **一键安装** 适用于15+ MCP客户端。
## 安装
需要 [uv](https://docs.astral.sh/uv/getting-started/installation/) （推荐）：
```bash
# 作为独立工具安装（不会影响您的全局Python环境）
uv tool install "nodriver-mcp @ git+https://github.com/andresolbach/nodriver-mcp-server.git@main"
```
> 使用上游 [`nodriver`](https://pypi.org/project/nodriver/) `>=0.50.3`，其中包含Chrome 146+ CDP修复（`sameParty` 从 `Cookie` 中删除，`privateNetworkRequestPolicy` → `localNetworkAccessRequestPolicy`) — **验证为适用于Chrome 150**。`pip install` 也有效，但 `uv tool install` 保持其隔离。
您还需要本地安装 **Google Chrome** （自动检测）。
### 升级
```bash
uv tool upgrade nodriver-mcp
```
## 需求和测试版本
本服务器中的每个工具都针对 **Google Chrome 150** 和 **nodriver 0.50.3** 在 **Python 3.12.11 / Windows 11** （也支持macOS和Linux）进行了端到端测试。因为nodriver直接通过CDP与Chrome通信并跟踪上游Chrome更改，所以它在Chrome自动更新时继续工作。
| 组件 | 需求 | 验证版本 |
|-----------|-------------|------------------|
| Python | 3.12+ | 3.12.11 |
| Google Chrome | 任意近期稳定版 | 150.0.7871.101 |
| 操作系统 | Windows / macOS / Linux | Windows 11 |
| `nodriver` | >= 0.50.3 | 0.50.3 |
| `mcp` (MCP SDK) | >= 1.26.0, < 2 | 1.26.0 |
| `pillow` | >= 12.1.1 | 12.1.1 |
| `tomli-w` | >= 1.0.0 | 1.2.0 |
pip包/版本也列在 [`requirements.txt`](requirements.txt) 中（`pip install -r requirements.txt`），但推荐使用`uv tool install`进行完全固定的、可复制的安装。
## 一键MCP客户端安装
```bash
# 交互式客户端选择器（终端TUI）
nodriver-mcp install
# 安装到特定客户端
nodriver-mcp install claude,cursor,kiro
# 卸载
nodriver-mcp uninstall claude
# 列出所有支持的客户端
nodriver-mcp --list-clients
# 打印MCP配置JSON（用于手动安装）
nodriver-mcp --config
# 项目级配置（写入.cursor/mcp.json，.mcp.json等）
nodriver-mcp install --scope project
```
**支持的客户端：** Claude Desktop，Claude Code，Cursor，Windsurf，Codex，Gemini CLI，Copilot CLI，Kiro，VS Code，Cline，Roo Code，Amazon Q，Warp，Opencode，Trae。
> Claude Code VS Code扩展程序共享Claude Code的配置（`~/.claude.json`），因此安装到 `claude-code` 同时适用于CLI和扩展程序。
## 环境变量
| 变量 | 描述 | 默认值 |
|----------|-------------|---------|
| `NODRIVER_HEADLESS` | 无头模式（`true`/`false`） | `false` |
| `NODRIVER_USER_DATA_DIR` | 显式持久Chrome配置文件目录（覆盖默认） | 临时配置文件，自动删除每个会话 |
| `NODRIVER_BROWSER_PATH` | Chrome可执行文件路径 | 自动检测 |
| `NODRIVER_PROXY` | 代理服务器地址 | 无 |
| `NODRIVER_ENABLE_TRANSLATE` | 设置`true`以重新启用Chrome的Google Translate弹出窗口 | 禁用 |
| `NODRIVER_ENABLE_EXTENSIONS` | 设置`true`以允许外部安装的Chrome扩展程序（及其提示） | 禁用 |
默认情况下，浏览器启动时是干净的，用于自动化： **Google Translate弹出窗口被抑制** ， **外部安装的Chrome扩展程序被阻止** （因此您不会收到“扩展程序需要您的关注”的提示）。通过上述env变量或运行时使用 `set_browser_flags` 工具重新启用两者 — 该工具还可以设置 **任何其他Chrome启动标志** （例如 `--lang=de-DE`， `--window-size=1280,800`）通过其 `extra_args` 参数。浏览器还会在调用之间 **自动恢复** ，如果Chrome在调用之间关闭或崩溃 — 工具会重新启动它而不是失败。
## 配置文件和同时运行多个实例
默认情况下，每个服务器实例都使用 **全新的临时配置文件** 启动Chrome，该配置文件由nodriver创建并自动删除。这意味着您可以同时从 **Claude Desktop、Claude Code和VS Code扩展程序** 运行nodriver — 每个实例都有自己的隔离Chrome，它们永远不会争夺共享配置文件。无需配置，无需检测逻辑，无需清理。
当您想要 **在会话之间重用登录** 时，创建一个命名的持久配置文件并切换到它：
- `list_profiles` — 列出持久配置文件并显示活动的一个
- `create_profile(name, activate=false)` — 创建可重用的配置文件
- `use_profile(name)` — 切换到持久配置文件（`""`/`"temp"` 返回临时）
- `use_temp_profile` — 切换回临时配置文件
- `delete_profile(name)` — 删除持久配置文件
持久配置文件位于 `~/.nodriver-mcp/profiles/<name>`。您仍然可以通过 `NODRIVER_USER_DATA_DIR` 环境变量强制使用固定的全局配置文件。
## 工具（56）
自动在每个标签页上启用网络收集。控制台收集是按需开启的：当您想要 `list_console_messages` / `get_console_message` 开始收集事件时，请调用 `enable_console_collection`。这样，默认情况下 `Runtime.enable()` 被禁用，以防网站检测到附加的调试器。
对于仅限移动的网站，请直接将 `device` 传递给 `new_page(...)` 或 `navigate_page(...)`，以便第一个真实请求已经携带移动信号。
| 类别 | 工具 |
|----------|-------|
| **输入自动化（10）** | `click` · `click_at` · `hover` · `fill` · `fill_form` · `type_text` · `press_key` · `drag` · `upload_file` · `handle_dialog` |
| **导航（10）** | `navigate_page` · `new_page` · `close_page` · `close_browser` · `list_pages` · `select_page` · `wait_for` · `wait_for_selector` · `scroll_page` · `scroll_to_selector` |
| **快照和调试（10）** | `take_screenshot` · `take_snapshot` · `get_page_content` · `query_selector` · `evaluate_script` · `save_pdf` · `enable_console_collection` · `disable_console_collection` · `list_console_messages` · `get_console_message` |
| **网络监控（3）** | `list_network_requests` · `get_network_request` · `block_resources` |
| **设备模拟（4）** | `emulate` · `emulate_device` · `reset_emulation` · `resize_page` |
| **性能（3）** | `performance_start_trace` · `performance_stop_trace` · `take_memory_snapshot` |
| **Cookie和存储（5）** | `get_cookies` · `set_cookie` · `clear_cookies` · `get_local_storage` · `set_local_storage` |
| **会话管理（3）** | `save_session` · `load_session` · `list_sessions` |
| **配置文件和浏览器（6）** | `list_profiles` · `create_profile` · `use_profile` · `use_temp_profile` · `delete_profile` · `set_browser_flags` |
| **反检测助手（2）** | `cf_verify` · `bypass_insecure_warning` |
## 与chrome-devtools-mcp比较
| 功能 | chrome-devtools-mcp | nodriver-mcp-server |
|---------|---------------------|---------------------|
| 浏览器后端 | Puppeteer（ChromeDriver） | nodriver（直接CDP） |
| WebDriver指纹 | ❌ 暴露 | ✅ 无 |
| `navigator.webdriver` | ❌ `true` | ✅ `undefined` |
| Cloudflare绕过 | ❌ | ✅ 内置 `cf_verify` |
| 安装方法 | npx | uv tool install |
| 语言 | TypeScript / Node.js | Python |
| 工具覆盖 | 29个工具 | 56个工具 |
未实现工具：`performance_analyze_insight` （需要DevTools前端跟踪解析器），`lighthouse_audit` （需要Lighthouse Node API），`screencast_start/stop` （需要ffmpeg + Puppeteer），扩展程序管理（实验性）。
## 用例
- **抓取Cloudflare / anti-bot站点** （DataDome，PerimeterX，hCaptcha挑战）而不会被指纹识别或阻止。
- **让AI代理浏览真实的网络** — Claude，Cursor，Windsurf和其他LLM代理可以登录，填写表单，点击，读取页面和截图。
- **自动化身份验证工作流** 并在会话之间重用登录，使用持久配置文件。
- **LLM驱动的网络研究和数据提取** ，使用紧凑的，可访问性树快照而不是脆弱的截图。
- **端到端/ QA测试** ，使用设备模拟，网络+控制台检查和性能跟踪。
- **不被检测的Playwright，Puppeteer和Selenium替代品** ，用于代理浏览。
## 常见问题
**这是chrome-devtools-mcp的不被检测的替代品吗？**
是的。它提供了相同的工具表面，但通过nodriver（直接CDP）驱动Chrome，因此 `navigator.webdriver` 为 `undefined` ，并且没有WebDriver/CDP指纹可供反机器人系统检测。
**它可以绕过Cloudflare吗？**
它配备了一个 `cf_verify` 工具，可以解决Cloudflare的“验证你是人类”的挑战，并且它的不被检测的配置文件避免了大多数机器人检查。（没有工具可以保证绕过每种保护。)
**支持哪些客户端？**
一键安装可用于15+ MCP客户端：Claude Desktop，Claude Code，Cursor，Windsurf，Codex，Gemini CLI，Copilot CLI，Kiro，VS Code，Cline，Roo Code，Amazon Q，Warp，Opencode，Trae。
**我可以同时在多个客户端上运行它吗？**
是的。每个实例默认使用自己的临时Chrome配置文件，因此Claude Desktop，Claude Code和VS Code扩展程序可以 **同时** 使用nodriver而不会发生冲突。
**无头或可见浏览器？**
默认情况下是一个真正的Chrome窗口；设置 `NODRIVER_HEADLESS=true` 为无头。
**如何在会话之间保持登录？**
使用 `create_profile` 创建持久配置文件并使用 `use_profile` 切换到它，或者使用 `save_session` / `load_session`。
**它在Windows / macOS / Linux上运行吗？**
是的，所有三个平台。 在Windows 11上使用Chrome 150和Python 3.12进行了测试。
## 更新日志
参见 [CHANGES.md](CHANGES.md)。亮点：默认情况下使用临时配置文件，以便多个实例可以同时运行（+命名持久配置文件），迁移到上游 `nodriver 0.50.3` （Chrome 150验证），并修复了几个以前损坏的工具 — `fill`/`fill_form`，`evaluate_script`带有元素参数，`select_page`选项卡切换，`press_key`修饰符和弦（Ctrl+A/C/V），网络/控制台查找索引和Windows安装程序崩溃。
## 致谢
基于 [`nodriver-mcp`](https://github.com/Saber-CC/nodriver-mcp) 由 **Saber-CC** （MIT）创建。浏览器后端由 [`nodriver`](https://github.com/ultrafunkamsterdam/nodriver) （ultrafunkamsterdam）提供。工具表面镜像 [`chrome-devtools-mcp`](https://github.com/ChromeDevTools/chrome-devtools-mcp)。
## 许可证
[MIT](LICENSE)
