内容
# Browser MCP Server
[](https://opensource.org/licenses/MIT)
通过 Chrome/Edge 扩展直接操作真实浏览器的 MCP 服务器。相对于 Playwright 等无头方案的轻量替代方案，直接操作真实浏览器，天然支持登录态页面。
适用于任何支持 MCP 协议（Model Context Protocol）的客户端，如各类 AI 编程助手。
## 架构
```
MCP 客户端 (任何支持 MCP 的 AI 编程工具)
│ stdio JSON-RPC
▼
mcp-server.ts
│ WebSocket ws://127.0.0.1:18765
▼
Chrome 扩展 (service worker)
│ chrome.debugger / tabs / cookies API
▼
真实浏览器页面
```
非无头、不走 WebDriver、不依赖 Selenium。页面就是你日常用的浏览器，cookie/登录态天然保留。
## 前提条件
- Node.js >= 18
- Chrome 或 Edge 浏览器
## 安装
### 1. 加载 Chrome/Edge 扩展
1. 打开 Chrome → `chrome://extensions/`（Edge 用 `edge://extensions/`）
2. 打开"开发人员模式"
3. "加载解压缩的扩展" → 选择 `extensions/tmwd-cdp-bridge` 目录
确认工具栏出现扩展图标。
### 2. 安装依赖
```bash
cd /path/to/browser-mcp
npm install
```
### 3. 启动 MCP 服务器
```bash
npx tsx mcp-server.ts
```
看到两行输出即成功：
```
[ws] Listening on :18765
[ws] Extension connected
```
扩展的 service worker 可能延迟几秒连接，等出现 `Extension connected` 即可。
### 4. 配置 MCP 客户端
在任意支持 MCP 的 AI 编程工具中注册此服务，`command` 指向 `mcp-server.ts`：
```json
{
"mcpServers": {
"browser": {
"command": "npx",
"args": ["tsx", "/path/to/browser-mcp/mcp-server.ts"],
"enabled": true
}
}
}
```
> 请将 `/path/to/browser-mcp` 替换为你的实际项目路径。
重启 AI 编程工具，即可在对话中调用所有 browser 工具。
## 所有工具
| 工具 | 参数 | 说明 |
|------|------|------|
| `connect` | 无 | 检查扩展是否已连接 |
| `tabs` | 无 | 列出所有打开的标签页（id, url, title） |
| `open_tab` | `url`, `active?` | 新标签页打开 URL |
| `switch_tab` | `tabId` | 切换到指定标签页 |
| `close_tab` | `tabId` | 关闭指定标签页 |
| `navigate` | `url`, `tabId?` | 当前/指定标签页导航到 URL |
| `snapshot` | `tabId?` | 获取页面可见文本内容 |
| `click` | `selector`, `tabId?` | 点击匹配 CSS 的元素 |
| `screenshot` | `tabId?` | 截屏，返回 base64 PNG |
| `evaluate` | `code`, `tabId?` | 在页面 MAIN 世界执行 JS，返回结果 |
| `type` | `text`, `tabId?` | 在焦点元素输入文本（CDP Input.insertText） |
| `fill` | `selector`, `value`, `tabId?` | 通过 CSS 选择器填充表单字段，触发 input/change 事件 |
| `press_key` | `key`, `tabId?` | 发送键盘按键（Enter / Escape / Tab / ArrowDown 等） |
| `wait_for` | `selector`, `timeout?`, `tabId?` | 轮询等待 CSS 选择器出现（100ms 间隔，默认 10s 超时） |
### 典型工作流
```
1. connect → 确认浏览器在线
2. tabs → 看当前有什么标签页
3. navigate(url) → 打开目标页面
4. snapshot → 读页面内容
5. click(selector) → 点链接/按钮
6. snapshot → 读新内容
7. evaluate(code) → 执行自定义 JS
```
## 最佳实践
### 1. 导航后等页面加载完再 snapshot
`navigate` 返回后页面可能还在加载。建议工具调用链中给 AI 足够的上下文判断。
### 2. tabId 传递
所有操作默认在当前活动标签页执行。如果打开了多个标签页，AI 会自动用 `tabs` 查看可用标签页，然后传入 `tabId` 精确定位。
### 3. click 选择器
优先用语义化的 CSS 选择器：
```
good: a[href*="/article/"] #search-button
bad: body > div > p > a .c-OMlI
```
### 4. evaluate 适合什么
- 提取结构化数据（JSON 格式的表格、列表）
- 触发页面 JS 函数
- 读取页面内部状态（`window.__INITIAL_STATE__` 等）
- 滚动、悬停等无法用 click 完成的操作
例子：
```
evaluate(code: "JSON.stringify([...document.querySelectorAll('a')].map(a => ({text:a.textContent, href:a.href})))")
```
## 注意事项
- **扩展 service worker 可能休眠**：Chrome MV3 的 service worker 约 30s 无活动后休眠。首次调用加 1-2s 唤醒延迟。服务器每 ~24s 发送 keepalive 维持连接
- **CDP 免 CSP**：`evaluate` 走 CDP `Runtime.evaluate`，不受页面 CSP 限制，不需要 `eval`/`Function`。比 `scripting.executeScript` 快 100-1000x
- **URL 重定向**：某些网站（百度、微博）有跳转中间页，navigate 返回的可能不是最终 URL
- **单扩展实例**：目前只支持一个浏览器实例连接
## 安全说明
- WebSocket 服务器仅绑定 `127.0.0.1:18765`，不暴露于外部网络
- `evaluate` 工具可在页面 MAIN 世界执行任意 JavaScript，具有与页面本身相同的权限
- 任何能访问本机的本地进程均可连接 WebSocket 并控制浏览器，请确保运行环境可信
## 性能参考
| 操作 | 典型耗时 |
|------|---------|
| snapshot | 7-40 ms |
| click | 20-40 ms |
| evaluate | 5-10 ms |
| screenshot | 60-105 ms |
| navigate | 300-3600 ms（网络开销）|
| open_tab | 3-5 ms |
## 贡献
欢迎提交 Issue 和 Pull Request。请确保代码风格一致并通过 `npm run build` 类型检查。
## 许可证
MIT — 详见 [LICENSE](./LICENSE) 文件。
