142 lines
5.5 KiB
Markdown
142 lines
5.5 KiB
Markdown
# browser-mcp-gateway
|
||
|
||
把本机的 [browser-mcp](https://github.com/Agent360dk/browser-mcp)（Chrome 扩展 + 本地 stdio MCP server）桥接到局域网，让其他主机远程驱动这台机器上的 Chrome 浏览器，用于网页爬取、自动化操作等场景。
|
||
|
||
## 架构
|
||
|
||
```
|
||
本机 MCP client ──stdio──┐
|
||
├─→ 本机 WS 中枢(127.0.0.1:9876) ─→ Chrome 扩展 ─→ Chrome
|
||
局域网主机 ──HTTP──→ 本网关 ──stdio──┘ (gateway 上游 spawn browser-mcp)
|
||
```
|
||
|
||
网关内部 spawn 一个 browser-mcp stdio 进程作为上游（自动重连），对外在同一端口暴露两类接口，所有接口均需 Bearer 认证（也支持 `?token=` 查询参数）。
|
||
|
||
## 配套组件
|
||
|
||
本项目网关依赖 browser-mcp 的两半：**Chrome 扩展**（驱动浏览器）和 **stdio MCP server**（与扩展配对）。本项目仓库已自带扩展，无需再装 npm 包来获取扩展。
|
||
|
||
### 1. 安装 Chrome 扩展（项目自带 `extension/`）
|
||
|
||
1. 打开 Chrome，地址栏输入 `chrome://extensions/`
|
||
2. 右上角打开 **开发者模式**
|
||
3. 点击 **加载已解压的扩展程序**，选择本项目下的 `extension/` 目录
|
||
4. 点击工具栏扩展图标（Agent360 Browser MCP），确认与本地 server 配对连接（扩展会连接 `127.0.0.1:9876`）
|
||
|
||
> `extension/` 来自 npm 包 `@agent360/browser-mcp@1.30.0` 自带的未打包扩展（Manifest V3），升级时可从新版 npm 包重新拷贝。
|
||
|
||
### 2. 安装 stdio 版本 MCP server（本机使用）
|
||
|
||
```bash
|
||
npm install -g @agent360/browser-mcp
|
||
```
|
||
|
||
在 MCP client 的配置中加入（以 Kimi Code 的 `~/.kimi-code/mcp.json` 为例）：
|
||
|
||
```json
|
||
"browser-mcp": {
|
||
"command": "node",
|
||
"args": ["C:\\Users\\<用户名>\\AppData\\Roaming\\npm\\node_modules\\@agent360\\browser-mcp\\bin\\cli.js"]
|
||
}
|
||
```
|
||
|
||
Linux / macOS 全局安装后一般为：
|
||
|
||
```json
|
||
"browser-mcp": {
|
||
"command": "node",
|
||
"args": ["/usr/local/lib/node_modules/@agent360/browser-mcp/bin/cli.js"]
|
||
}
|
||
```
|
||
|
||
> 网关（`gateway.js`）内部就是以上述 stdio 方式启动同一个 `cli.js` 作为上游，再由网关桥接到局域网。
|
||
|
||
### 来源与官网
|
||
|
||
- **本项目使用的分叉**：Agent360 Browser MCP —— GitHub: <https://github.com/Agent360dk/browser-mcp> ，npm: `@agent360/browser-mcp`
|
||
- **原版 BrowserMCP**：官网 <https://browsermcp.io> ，GitHub: <https://github.com/browsermcp/mcp>
|
||
|
||
## 接口
|
||
|
||
| 路径 | 说明 |
|
||
|---|---|
|
||
| `GET /` | HTML 使用说明页（含示例地址设置栏：默认当前访问 host:port，可自定义/重置） |
|
||
| `GET /docs` | HTML 格式 API 文档 |
|
||
| `GET /docs.json` | JSON 格式 API 文档（浏览器访问自动渲染为高亮 HTML，curl 获取原始 JSON） |
|
||
| `POST /mcp` | MCP Streamable HTTP 端点（无状态，仅 POST），供 MCP client 接入 |
|
||
| `GET /api/health` | 存活与上游状态 |
|
||
| `GET /api/tools` | 列出全部浏览器工具 |
|
||
| `POST /api/call` | 调用工具，body：`{"name": "工具名", "arguments": {...}}` |
|
||
|
||
## 快速开始
|
||
|
||
```bash
|
||
npm install
|
||
echo "你的token" > token.txt # 或使用环境变量 GATEWAY_TOKEN
|
||
npm start # 或双击 start-gateway.bat
|
||
```
|
||
|
||
默认监听 `0.0.0.0:9109`。
|
||
|
||
### 配置项（环境变量）
|
||
|
||
| 变量 | 默认值 | 说明 |
|
||
|---|---|---|
|
||
| `PORT` | `9109` | 监听端口 |
|
||
| `HOST` | `0.0.0.0` | 监听地址 |
|
||
| `GATEWAY_TOKEN` | 读取 `token.txt` | Bearer 认证 token |
|
||
| `BROWSER_MCP_CLI` | `%APPDATA%\npm\node_modules\@agent360\browser-mcp\bin\cli.js` | 上游 browser-mcp 入口 |
|
||
|
||
## 使用
|
||
|
||
### REST API（curl / 脚本）
|
||
|
||
```bash
|
||
TOKEN=你的token
|
||
curl -s http://10.1.1.6:9109/api/call \
|
||
-H "Authorization: Bearer $TOKEN" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"name":"browser_navigate","arguments":{"url":"https://example.com"}}'
|
||
```
|
||
|
||
### MCP client（Kimi Code）
|
||
|
||
`~/.kimi-code/mcp.json` 的 `mcpServers` 中加入（保存后新建会话生效）：
|
||
|
||
```json
|
||
"browser-remote": {
|
||
"url": "http://10.1.1.6:9109/mcp",
|
||
"headers": { "Authorization": "Bearer 你的token" }
|
||
}
|
||
```
|
||
|
||
### Claude Code
|
||
|
||
```bash
|
||
claude mcp add --transport http browser-remote http://10.1.1.6:9109/mcp \
|
||
--header "Authorization: Bearer 你的token"
|
||
```
|
||
|
||
## 注意事项
|
||
|
||
- **浏览器在网关所在机器上**：远程调用驱动的是本机 Chrome（Cookie、登录态共享），需保持 Chrome 的 browser-mcp 扩展处于连接状态。
|
||
- **会话隔离**：每个 MCP client 获得独立的浏览器会话（各自开标签页），互不干扰；但同一标签页不要两边同时操作。
|
||
- **防火墙**：Windows 需放行端口，建议限制来源网段（管理员 PowerShell）：
|
||
```powershell
|
||
New-NetFirewallRule -DisplayName "browser-mcp-gateway" -Direction Inbound -Protocol TCP -LocalPort 9109 -RemoteAddress 10.1.1.0/24 -Action Allow
|
||
```
|
||
- **截图路径限制**：`browser_screenshot` 的 `path` 参数只能写在网关进程工作目录内（browser-mcp 的安全限制），远程调用请传相对路径。
|
||
- **Token 即全部权限**：请勿泄露到不可信网络；`token.txt` 已加入 `.gitignore`。
|
||
- 持久化运行可挂到 Windows 任务计划程序（开机执行 `start-gateway.bat`）。
|
||
|
||
## 文件
|
||
|
||
```
|
||
gateway.js # 网关主程序：HTTP 服务 + 认证 + stdio 上游管理 + MCP 代理
|
||
pages.js # /、/docs、/docs.json 三个页面的 HTML/JSON 渲染
|
||
extension/ # 配套 Chrome 扩展（Agent360 Browser MCP，未打包）
|
||
package.json # 仅依赖 @modelcontextprotocol/sdk
|
||
token.txt # Bearer token（gitignore）
|
||
start-gateway.bat # Windows 启动脚本
|
||
```
|