BrowserMCP 本地版分享包

开箱即用的本地版 BrowserMCP：修复版 server + 改造版 Chrome 扩展，npm install 自动拉取依赖并打补丁，npm start 即可启动。

目录结构

browsermcp-share/
├── README.md                        # 本说明
├── AGENTS.md                        # 给 Agent 的快查指南
├── .gitignore
├── browsermcp-server/               # 本地修复版 MCP server
│   ├── package.json                 # 声明依赖 + postinstall 补丁脚本
│   ├── package-lock.json
│   ├── patch-server.js              # 自动打补丁脚本（npm install 后自动运行）
│   └── (.gitignore → node_modules/)
└── browsermcp-extension/            # 改造版 Chrome 扩展（Browser MCP 1.3.4 + 自动重连注入）
    ├── manifest.json                # 已增加 alarms 权限，保留原版 key（扩展 ID 不变）
    ├── background.js                # 已注入自动唤醒 + 自动选标签页逻辑
    ├── popup.html
    ├── content-scripts/
    ├── chunks/
    ├── assets/
    ├── icon/
    └── _locales/

为什么需要"本地修复版"

官方 npm 包 @browsermcp/mcp@0.1.3（2025-04 发布后维护停滞，npm latest 仍是 0.1.3）存在已知问题：

问题	表现	上游跟踪
server.close 自引用递归	退出时抛 RangeError: Maximum call stack size exceeded，残留 node 进程、9009 端口不释放	Issue #92、#163（CVSS 7.5），修复 PR #130/#181/#194 均未合并
Context.close() 后 stale ws 引用	关闭后仍持有已断开的 WebSocket 引用	同上

修复方式：patch-server.js 在 npm install 后自动运行（postinstall hook），对 node_modules/@browsermcp/mcp/dist/index.js 打两处补丁：

1. server.close 先保存原始函数再调用，消除自引用递归：

var originalServerClose = server.close.bind(server);
server.close = async () => {
  await originalServerClose();
  // ...
};

2. Context.close() 关闭后将 this._ws 置空，清除 stale 引用：

await this._ws.close();
this._ws = void 0;

扩展改造了什么

基于 Chrome 商店版 Browser MCP 1.3.4 复制改造（保留 manifest key → 扩展 ID 与原版一致），解决两个痛点：

1. 自动重连失效问题：MV3 service worker 在 WebSocket 断开约 30 秒后休眠，自带的每秒自动重连定时器停止 → 扩展无法自动连上重启后的 server。改造：manifest 增加 alarms 权限，background.js 注入 chrome.alarms 每 30 秒唤醒休眠的 worker，唤醒后顶层重连逻辑自动恢复。实测 server 启动后扩展 6 秒内自动连上（最坏 30 秒），全程无需手动点 Connect。

2. "No selected tab ID" 报错：卸载重装后 selectedTabId 丢失。改造：自动把当前活动标签页写入 chrome.storage.local["selectedTabId"]（@wxt-dev/storage 的 area:key 格式，键名去掉 local: 前缀），无需手动选标签页。

代价：Chrome 每次启动会显示"停用开发者模式扩展"横幅，点「保留」即可。

快速开始

1. 安装扩展（一次性）

1. 打开 chrome://extensions，右上角开启「开发者模式」
2. 移除已安装的原装 Browser MCP 扩展（同 ID 冲突，必须移除）
3. 点击「加载已解压的扩展程序」→ 选择 browsermcp-extension/ 文件夹
4. 点击扩展卡片上的刷新按钮（旋转箭头）重载
5. 把 Chrome 活动标签页切到要操作的目标页面，约 1.5 秒后扩展自动写入选中标签页

2. 安装 + 启动 server

cd browsermcp-server
npm install          # 自动拉取 @browsermcp/mcp@0.1.3 + 运行 postinstall 补丁
npm start            # 启动 server，监听 ws://localhost:9009

server 启动后监听 ws://localhost:9009，扩展会自动连上（无需手动 Connect）。

3. 在 MCP 客户端中注册（可选）

如果要在 Claude Desktop / Cursor 等客户端中作为 MCP server 使用，配置为 stdio 方式：

{
  "mcpServers": {
    "browsermcp": {
      "command": "node",
      "args": [
        "<本目录绝对路径>/browsermcp-server/node_modules/@browsermcp/mcp/dist/index.js"
      ]
    }
  }
}

常见问题

• 端口 9009 被占用：说明有残留的 server 进程，结束对应 node 进程后重试。
• 扩展连不上 server：确认 server 已启动；chrome://extensions 里点扩展的刷新按钮重载，等待最多 30 秒。
• 扩展 ID 冲突：本扩展保留原版 key，ID 与原装 Browser MCP 相同，安装前必须移除原版。
• 补丁没生效：重新运行 node patch-server.js 即可（脚本是幂等的）。

版本信息

• server：@browsermcp/mcp 0.1.3（npm 安装 + patch-server.js 自动补丁）
• 扩展：Browser MCP 1.3.4（改造版，扩展会随商店版升级而落后，如需新版需重新复制 + 注入）
• 适配：Chrome（Manifest V3），macOS / Windows / Linux