内容
# 浏览器 MCP 工具
适用于 **Chrome 和 Edge** 的 MCP 服务器，通过 **Chrome DevTools Protocol**：屏幕录制、全页截图和设备模拟。与 [mcp-selenium](https://github.com/angiejones/mcp-selenium) 相辅相成。
## 要求
- **Node.js 18+**
- **Chrome 或 Edge** (Chromium)
- **ffmpeg** 通过 `ffmpeg-static` 捆绑（仅录制时需要）
## 在 Cursor 中安装
```json
{
"mcpServers": {
"browser-tools": {
"command": "npx",
"args": ["-y", "browser-mcp-tools@latest"]
}
}
}
```
本地开发：
```json
{
"mcpServers": {
"browser-tools": {
"command": "node",
"args": ["/path/to/browser-mcp-tools/src/server.js"]
}
}
}
```
## 快速开始使用 mcp-selenium
1. 启动 Chrome 或 Edge 进行远程调试：
```json
{
"browser": "chrome",
"options": {
"arguments": ["--remote-debugging-port=9222", "--remote-allow-origins=*"]
}
}
```
2. 录制：
```
attach_auto → start_recording → （Selenium 操作）→ stop_recording
```
3. 全页截图（桌面版，默认）：
```
attach_auto → take_full_screenshot(outputPath: ~/Downloads/page.png)
```
## 设备模拟
默认视口为 **桌面版**。模拟是可选的，并且在 `clear_emulation` 或 `close_session` 之前 **持续生效**。
```
attach_auto
→ emulate_device(device: "iPhone 14")
→ （Selenium 导航/交互）
→ take_full_screenshot(outputPath: ~/Downloads/mobile.png)
→ clear_emulation()
```
列出可用设备：
```
list_devices
```
内置预设：iPhone 14、iPhone SE、Pixel 7、Galaxy S23、iPad。
### 自定义设备
创建 `~/.config/browser-mcp-tools/devices.json`：
```json
{
"my-iphone": {
"width": 400,
"height": 540,
"deviceScaleFactor": 1,
"mobile": true,
"touch": true
}
}
```
用户设备覆盖具有相同名称的内置预设。
使用环境变量 `BROWSER_MCP_TOOLS_DEVICES` 重写配置路径。
设备配置文件字段：
| 字段 | 是否必填 | 默认值 | 描述 |
| ------------------- | -------- | -------- | ----------------------------- |
| `width` | 是 | — | 视口宽度（CSS 像素） |
| `height` | 是 | — | 视口高度（CSS 像素） |
| `deviceScaleFactor` | 否 | `1` | 设备像素比率 |
| `mobile` | 否 | `false` | 移动视口提示 |
| `touch` | 否 | `mobile` | 触摸事件模拟 |
| `userAgent` | 否 | `null` | 自定义用户代理字符串 |
## 多会话
为每个浏览器传递唯一的 `sessionId`，或使用不同的调试端口（`9222`、`9223` 等）：
```
attach_auto(sessionId: "agent-a", debugPort: 9222)
attach_auto(sessionId: "agent-b", debugPort: 9223)
```
## 录制过程中切换标签页
```
switch_target(latest: true)
switch_target(url: "/checkout")
switch_target(windowHandle: "...")
```
## 工具
| 工具 | 描述 |
| ---------------------- | --------------------------------------------------- |
| `attach_auto` | 自动发现 Chrome/Edge CDP 调试端口并连接 |
| `attach_browser` | 连接到特定的 CDP 调试端口 |
| `start_browser` | 启动 Chrome/Edge 并附带调试端口连接 |
| `list_cdp_ports` | 扫描可连接的 CDP 调试端口 |
| `list_targets` | 列出调试端口上的页面目标 |
| `switch_target` | 在录制过程中切换标签页 |
| `start_recording` | 启动 CDP 屏幕录制 |
| `stop_recording` | 将帧编码为 MP4 |
| `take_full_screenshot` | 全页截图（整个可滚动内容） |
| `list_devices` | 列出内置和用户设备配置文件 |
| `emulate_device` | 应用持续的设备模拟 |
| `clear_emulation` | 恢复桌面视口 |
| `recording_status` | 会话状态 |
| `list_sessions` | 列出所有会话 |
| `close_session` | 关闭一个或所有会话 |
### `take_full_screenshot` 选项
| 参数 | 默认值 | 描述 |
| ------------ | --------- | ------------------------------ |
| `format` | `png` | 图片格式（`png` 或 `jpeg`） |
| `quality` | — | JPEG 质量 0-100 |
| `outputPath` | 临时文件 | 图片的绝对路径 |
### `start_recording` 选项
| 参数 | 默认值 | 描述 |
| ------------------------ | ------- | ---------------------------------- |
| `format` | `jpeg` | 帧格式（`jpeg` 或 `png`） |
| `quality` | `80` | JPEG 质量 |
| `everyNthFrame` | `1` | 每隔 N 帧捕获一次屏幕录制帧 |
| `maxWidth` / `maxHeight` | — | 可选的帧大小限制 |
### `stop_recording` 选项
| 参数 | 默认值 | 描述 |
| --------------- | --------- | ------------------------------------------ |
| `fps` | `10` | 输出视频帧率（仅编码时） |
| `outputPath` | 临时文件 | MP4 的绝对路径 |
| `cleanupFrames` | `true` | 编码后删除临时帧 |
## 工作原理
通过 CDP WebSocket 连接到附加的 Chrome/Edge 标签页。
- **录制：** `Page.startScreencast` 在视觉变化时捕获帧；ffmpeg 在 `stop_recording` 时编码为 MP4。
- **截图：** `Page.captureScreenshot` 带有 `captureBeyondViewport: true` 捕获整个可滚动页面。
- **模拟：** `Emulation.setDeviceMetricsOverride` + 可选的用户代理和触摸模拟。
**FPS** 仅影响 ffmpeg 编码速度 — 它不控制 CDP 发送屏幕录制帧的频率。
## 限制
- **延迟加载的内容** 可能不会出现在全页截图中，除非页面首先滚动。
- **非常长的页面** 可能达到内存或超时限制。
- **粘性页眉/页脚** 可能在全页捕获中重复出现。
- **Firefox / Safari** 不支持（无 CDP 屏幕录制）。
## 浏览器支持
| 浏览器 | 支持 |
| ------- | -------------------------------------------------------------------------------------------- |
| Chrome | ✅ |
| Edge | ✅ |
| Firefox | ❌ ([CDP removed in Selenium 4.29+](https://www.selenium.dev/blog/2025/remove-cdp-firefox/)) |
| Safari | ❌ |
## 开发
```bash
npm install
npm start
npm run check # lint + format + unit tests
npm run test:integration
```
## 许可证
Apache-2.0 — 见 [LICENSE](LICENSE)。
