Browser MCP Server

通过 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. 安装依赖

cd /path/to/browser-mcp
npm install

3. 启动 MCP 服务器

npx tsx mcp-server.ts

看到两行输出即成功：

[ws] Listening on :18765
[ws] Extension connected

扩展的 service worker 可能延迟几秒连接，等出现 Extension connected 即可。

4. 配置 MCP 客户端

在任意支持 MCP 的 AI 编程工具中注册此服务，command 指向 mcp-server.ts：

{
  "mcpServers": {
    "browser": {
      "command": "npx",
      "args": ["tsx", "/path/to/browser-mcp/mcp-server.ts"],
      "enabled": true
    }
  }
}

请将 /path/to/browser-mcp 替换为你的实际项目路径。

重启 AI 编程工具，即可在对话中调用所有 browser 工具。

所有工具

典型工作流

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 并控制浏览器，请确保运行环境可信

性能参考

贡献

欢迎提交 Issue 和 Pull Request。请确保代码风格一致并通过 npm run build 类型检查。

许可证

MIT — 详见 LICENSE 文件。