浏览器控制代理

浏览器多合作平台

MCP服务器+Chrome扩展程序，使编码代理（Claude Code等）能够完全控制真正的Chrome浏览器。多个Claude Code会话可以同时共享同一浏览器。

建筑

Claude Code #1 → MCP Server #1 ──┐
Claude Code #2 → MCP Server #2 ──┤  (pipe clients)
Claude Code #3 → MCP Server #3 ──┘
                                  │  Named pipe
                                  ▼
                    relay.js  (pipe server, spawned by Chrome)
                                  │  Chrome Native Messaging
                                  ▼
                    background.js  (Chrome Extension Service Worker)
                                  │  Chrome Extension APIs
                                  ▼
                              Web Pages

中继充当命名管道服务器。每个Claude Code会话都会生成自己的MCP服务器进程，该进程作为管道客户端连接到中继。中继器对请求进行多路复用，并通过匹配请求ID将响应路由回正确的MCP客户端。

先决条件

• Node.js 18+（必须在您的系统PATH中）
• 铬 或 边缘 浏览器
• 克劳德代码 （或任何兼容MCP的客户端）

设置

步骤1：安装依赖项并构建

cd /path/to/browser-mcp
npm install
npm run build

这将安装MCP SDK并将TypeScript服务器编译为 dist/mcp-server.js.

macOS注意事项： 做 不 将此项目保留在 ~/Downloads/ 文件夹。macOS系统策略阻止Chrome启动位于 ~/Downloads/.先将项目转移到其他地方（例如。 ~/browser-mcp 或 ~/Projects/browser-mcp).

步骤2：加载Chrome扩展程序

1. 打开Chrome浏览器并导航到 chrome://extensions
2. 启用 开发者模式 使用右上角的切换按钮
3. 点击 装载时未包装
4. 选择 extension/ 此项目中的文件夹（例如。 C:\Browser MCP\extension)
5. 扩展 “浏览器MCP桥” 将出现--复制 扩展ID 如下图所示
   • 它看起来像： abcdefghijklmnopqrstuvwxyz012345

步骤3：注册本机消息主机

运行安装程序脚本，传递上一步中的扩展ID：

node install.js <your-extension-id>

例如：

node install.js abcdefghijklmnopqrstuvwxyz012345

这做了两件事：

• 将本机消息主机清单文件写入每个受支持浏览器的相应目录（macOS上的Chrome、Chrome Canary、Edge、Edge Canary；Windows/Linux上的Chrome和Edge）
• 在Windows上，在Windows注册表中注册清单路径
• 清除以前安装的任何过时的中继进程或套接字文件

重要提示： 如果重新安装扩展并获得新的扩展ID，请使用新ID重新运行此命令。

步骤4：重新加载扩展

运行安装程序后，返回 chrome://extensions 然后单击 重新加载 浏览器MCP桥扩展上的按钮（圆形箭头）。这允许扩展程序获取新注册的本机消息传递主机。

步骤5：将MCP服务器添加到Claude Code

选项A--CLI命令：

claude mcp add browser-mcp -- node "C:/Browser MCP/dist/mcp-server.js"

选项B——手动添加到Claude Code配置文件中(.claude.json 在您的项目根目录或全局 claude_desktop_config.json):

{
  "mcpServers": {
    "browser-mcp": {
      "command": "node",
      "args": ["C:/Browser MCP/dist/mcp-server.js"]
    }
  }
}

步骤6：验证它是否有效

启动一个新的Claude Code会话，并问它这样的问题：

“打开https://example.com在浏览器中获取页面文本”

您应该看到Chrome中打开了一个新选项卡，Claude返回了页面内容。

安装后

设置完成后，您通常 不需要做任何事情 开始新会话时：

可用工具

使用模式

网络搜索

1. browser_open    → navigate to https://www.bing.com
2. browser_state   → find the search input element index
3. browser_input   → type the search query into the input
4. browser_keys    → press Enter to submit
5. browser_state   → read the search result links and snippets
6. browser_open    → navigate to a promising result URL
7. browser_get_text → extract the page content

阅读网页

1. browser_open    → navigate to the URL
2. browser_get_text → extract readable text content

填写表格

1. browser_open    → navigate to the form page
2. browser_state   → get element indices for all form fields
3. browser_input   → fill each field by its index
4. browser_click   → click the submit button

运作原理

1. Chrome 扩展 (extension/background.js)-使用扩展API控制Chrome选项卡的Manifest V3服务工作者。它在加载时连接到本地消息主机，并执行通过该通道接收到的浏览器命令（打开、单击、键入等）。

2. 中继 (relay/relay.js)——Chrome作为原生消息主机生成的一个小型Node.js进程。它创造了一个 命名管道服务器 (\\.\pipe\browser-mcp-bridge 在Windows上）以及Chrome的本机消息传递协议（stdin/stdout上的长度前缀JSON）和命名管道（换行符分隔的JSON）之间的桥梁。它跟踪哪个管道客户端发送了每个请求，并正确路由响应。

3. MCP 服务器 (dist/mcp-server.js)--Claude Code为每个会话生成的Node.js进程。它连接到继电器的命名管道作为 客户端，通过stdio上的MCP协议注册16个浏览器工具，并将MCP工具调用转换为中继请求。多个MCP服务器实例可以同时连接。

4. 请求流程： MCP客户端→ MCP 服务器→ 命名管道→ 中继→ Chrome原生消息→ 扩展→ Chrome浏览器→ 响应返回相同的路径。

故障排除

“浏览器扩展未连接”

这意味着MCP服务器无法连接到中继的命名管道。可能的原因：

1. 扩展未加载 首选 chrome://extensions 并验证“浏览器MCP桥”是否已列出并启用
2. 本地消息主机未注册 --重新运行 node install.js <extension-id>
3. 扩展需要重新加载 --点击扩展卡上的重新加载按钮 chrome://extensions
4. Chrome未运行 --中继仅在Chrome运行并加载扩展程序时存在

扩展负载，但工具不起作用

• 点击 “检查视图：服务人员” 在扩展卡上 chrome://extensions 打开控制台
• 寻找 [BMCP-Bridge] 记录消息以诊断连接问题

本机消息传递错误

• 验证Node.js是否在您的系统PATH中：运行 node --version 从终端
• 在Windows上，验证注册表项是否存在：
  • HKCU\Software\Google\Chrome\NativeMessagingHosts\com.browser.mcp.relay
  • HKCU\Software\Microsoft\Edge\NativeMessagingHosts\com.browser.mcp.relay
• 重新运行 node install.js <extension-id> 重新生成清单和注册表项

macOS特定问题

• 连接后立即“本机主机已退出” --检查项目是否位于 ~/Downloads/.MOSX系统策略阻止Chrome的本机消息传递子进程读取中的文件 ~/Downloads/.将项目移动到另一个位置（例如。 ~/browser-mcp)并重新运行 node install.js.
• 隔离属性 --从互联网下载的文件具有隔离扩展属性，可能会阻止执行。用以下方式删除它们：
  复制

  xattr -dr com.apple.quarantine /path/to/browser-mcp/
  

• Chrome找不到Node.js --Chrome以最小的PATH启动本机消息主机(/usr/bin:/bin:/usr/sbin:/sbin)这不包括自制啤酒(/opt/homebrew/bin)或nvm目录。安装程序会自动将绝对路径解析为 node 并将其写入 relay.sh.如果您更改了Node.js安装，请重新运行 node install.js.
• 检查继电器日志 --继电器将诊断日志写入 /tmp/browser-mcp-relay.log （或 $TMPDIR/browser-mcp-relay.log).检查此文件是否有错误：
  复制

  cat /tmp/browser-mcp-relay.log
  

• 中继过程陈旧 --如果之前的中继进程仍在运行，则新的中继进程将与EADDRINUSE一起退出。重新 node install.js 自动清理过时的进程，或手动：
  复制

  pkill -f relay.js
  rm -f /tmp/browser-mcp-bridge.sock
  

多个Claude Code会话

所有会话共享同一浏览器。一个会话打开的选项卡通过以下方式对其他会话可见 browser_sessions。如果两个会话试图同时与同一选项卡交互，结果可能无法预测——每个会话都应该使用自己的选项卡。

项目结构

Browser MCP/
├── src/
│   └── mcp-server.ts       # MCP server (pipe client + tool definitions)
├── dist/
│   └── mcp-server.js       # Compiled server (this is what Claude Code runs)
├── extension/
│   ├── manifest.json        # Chrome MV3 extension manifest
│   ├── background.js        # Service worker — executes browser commands
│   └── content.js           # Fallback content extraction script
├── relay/
│   ├── relay.js             # Native messaging relay (pipe server + request router)
│   ├── relay.bat            # Windows wrapper for relay.js
│   └── relay.sh             # macOS/Linux wrapper for relay.js (generated by install.js)
├── install.js               # One-time setup: registers native messaging host
├── package.json
└── tsconfig.json