内容
mcp-patchright
🛡️ 不可检测的浏览器MCP服务器 — 59种工具，Patchright驱动，无CDP指纹。
[![npm]](https://npmjs.com/mcp-patchright) [![MCP]](https://modelcontextprotocol.io)
通过Cloudflare / Akamai / Kasada / Datadome。
## 为什么选择Patchright而不是Playwright？
| | Playwright | Patchright |
|---|---|---|
| `Runtime.enable` | ✅ 发送（可检测） | ❌ 已移除 |
| `Console.enable` | ✅ 发送 | ❌ 已移除 |
| `--enable-automation` 标志 | ✅ 存在 | ❌ 已移除 |
| `navigator.webdriver` | `true` | `false` / `undefined` |
| 反机器人逃避 | ❌ | ✅ |
查看 [完整比较](#) 获取详细信息。
## 快速开始
```bash
npm i -g mcp-patchright
mcp-patchright --port 9321 --host 127.0.0.1
```
### 与Claude / GPT / 代理一起使用
```json
{
"mcpServers": {
"patchright": {
"command": "npx",
"args": ["mcp-patchright", "--port", "9321", "--host", "127.0.0.1"]
}
}
}
```
## 功能
- **41种MCP工具** — 完整的浏览器自动化表面
- **3种传输方式** — stdio, SSE, Streamable HTTP (`/mcp`)
- **持久化配置文件** — 真实的Chrome配置文件，在多个会话中重复使用
- **多页面** — 标签页管理（新建，列出，切换，关闭）
- **CDP附件** — 控制一个已经运行的Chrome
- **网络跟踪 + 拦截** — 请求列表/详细信息，离线切换，阻塞/模拟路由
- **会话导入/导出** — `browser_storage_save` / `browser_storage_load` （cookie + localStorage）
- **粒度存储** — 按键cookie / localStorage / sessionStorage CRUD（`browser_cookie_*`，`browser_localstorage_*`，`browser_sessionstorage_*`）
- **身份验证API请求** — `browser_api_request` 重用会话cookie（混合爬虫）
- **文本/HTML提取** — `browser_get_visible_text` / `_html` （token-light）
- **Iframe感知** — 将 `frameSelector` 传递给任何元素工具（click/fill/type/hover/press/wait_for/select/drag）在iframe内操作
- **PDF导出** — `browser_save_pdf` 通过CDP（在headed/stealth模式下工作）
- **视频记录** — `browser_start` with `recordVideo`, `browser_video_save`; .webm 在 `browser_close` 时刷新
- **元素高亮** — `browser_highlight` / `browser_hide_highlight` 叠加层用于截图和录制
- **隐身配置文件** — 代理 / 地理位置 / 语言环境 / 时区 / 颜色方案
- **控制台捕获** — 实时控制台消息流
- **指纹检查** — `browser_fingerprint_check` 诊断
## 工具
完整比较HTML见 [/docs/tool-comparison.html](docs/tool-comparison.html).
- `browser_start`
- `browser_status`
- `browser_navigate`
- `browser_new_page`
- `browser_pages`
- `browser_switch_page`
- `browser_close_page`
- `browser_snapshot`
- `browser_take_screenshot`
- `browser_click`
- `browser_fill`
- `browser_type`
- `browser_hover`
- `browser_press_key`
- `browser_wait_for`
- `browser_evaluate`
_fingerprint_check`
- `browser_navigate_back`
- `browser_select_option`
- `browser_handle_dialog`
- `browser_file_upload`
- `browser_network_requests`
- `browser_network_request`
- `browser_console_messages`
- `browser_resize`
- `browser_drag`
- `browser_fill_form`
- `browser_run_code_unsafe`
- `browser_network_state_set`
- `browser_api_request`
- `browser_get_visible_text`
- `browser_get_visible_html`
- `browser_iframe_click`
- `browser_iframe_fill`
- `browser_route_block`
- `browser_route_mock`
- `browser_route_clear`
- `_save`
- `browser_storage_load`
- `browser_cookie_list`
- `browser_cookie_get`
- `browser_cookie_set`
- `browser_cookie_delete`
- `browser_cookie_clear`
- `browser_localstorage_list`
- `browser_localstorage_get `browser_localstorage_set`
- `browser_localstorage_delete`
- `browser_localstorage_clear`
- `browser_sessionstorage_list`
- `browser_sessionstorage_get`
- `browser_sessionstorage_set`
- `browser_sessionstorage_delete`
- `browser_sessionstorage_clear`
- `browser_video_save`
- `browser_highlight`
- `browser_hide_highlight`
- `browser_save_pdf`
- `browser_close`
## 开发
```bash
npm install
npm run build
node dist/index.js
```
默认情况下，`browser_start` 通过patchright启动Chromium，带有持久化配置文件：
```textestro/stealth-playwright-mcp/profiles可以通过 `userDataDir` 工具参数或 `STEALTH_PLAYWRIGHT_USER_DATA_DIR` 环境变量覆盖它。
要附加到一个已经运行的Chrome，而不是启动一个新的，可以使用远程调试启动Chrome，并将 `cdpEndpoint` 传递给 `browser_start`:
```bash
/Applications/Google\\ Chrome.app/Contents/MacOS/Google\\ Chrome \\
--remote-debugging-port=9222 \\
--user-data-dir=$HOME/.maestro/stealth-playwright-mcp/profiles/cdp
```
```json
{ "cdpEndpoint": "http://127.0.0.1:9222" }
```
`browser_snapshot` 返回Playwright的AI aria快照。使用该快照中的 `[ref=eN]` 值与 `browser_click`，`browser_fill`，`browser_type`，`browser_hover`，`browser_press` 和 `browser_wait_for`，方法是将 `{ "ref": "eN" }` 传递给它们。CSS选择器通过 `{ "selector": "..." }` 仍然受支持。
MCP配置示例：
```json
{
"mcpServers": {
"stealth-playwright": {
"command": "node",
"args": ["/Users/maestrobot/stealth-playwright-mcp/dist/index.js"]
}
}
```
## 方向
已完成：
- ✅ 持久化用户数据目录
- ✅ CDP附加到真实Chrome
- ✅ 代理 / 时区 / 语言环境 / 地理位置配置文件
- ✅ 面向LLM的无障碍快照，用于页面控制
- ✅ 指纹诊断
网络拦截（阻塞/模拟）
- ✅ 会话导入/导出（storageState）
- ✅ PDF导出
- ✅ 身份验证API请求（重用浏览器cookie）
- ✅ 轻量级文本/HTML提取
- ✅ Iframe操作
接下来：
- rebrowser-playwright后端
- 代码生成会话
- 基于坐标（视觉）的点击
- 跟踪/视频录制
