浏览器mcp-lite
繁体中文 |英语
让你的AI助手看到你的真实浏览器——大约500行代码。
最低限度的身份验证安全 主控程序 该服务器允许AI助手在您的实际Chrome浏览器中阅读页面、截图和运行脚本,而您现有的登录会话保持不变。```
AI Assistant ──HTTP POST──▶ MCP Server (:12307) ──WebSocket──▶ Chrome Extension ──▶ DOM
(token auth) (ws://) (minimal permissions)
## 为什么要建立自己的?
现有的浏览器MCP解决方案有:
- **太重了** — mcp铬 需要 `debugger`, `history`, `` 权限,发送您无法审核的压缩代码
- **仅限无头** — 剧作家MCP 启动新浏览器,看不到您登录的会话
- **依赖云** --Browserbase等通过第三方服务器路由您的页面
浏览器mcp-lite采用了不同的方法:
||mcp chrome|剧作家mcp| **浏览器mcp-lite** |
|---|---|---|---|
|读取您的真实浏览器|是|否(无头)| **是** |
|MCP端点上的身份验证|否|否| **令牌身份验证** |
|扩展权限|8+|N/A| **5(最小)** |
|您可以审计的代码|精简|是| **~500条线路** |
|登录会话|是|否| **是** |
## 它做什么
通过标准MCP协议公开的四种工具:
|工具|描述|返回|
|------|-------------|---------|
| `list_tabs` |列出所有打开的选项卡| `[{id, url, title, active}]` |
| `read_page` |将页面读取为可访问性树|结构化文本(令牌高效)|
| `screenshot` |捕获可见区域|Base64 PNG图像|
| `inject_script` |在选项卡中运行自定义JS |脚本返回值|
## 快速启动
### 1.安装并启动服务器
**选项A--npx(不需要克隆):**```bash
npx browser-mcp-lite
选项B--克隆:```bash
git clone https://github.com/notoriouslab/browser-mcp-lite.git
cd browser-mcp-lite/server
npm install
node index.js
第一次运行时,会自动生成一个令牌。服务器打印完整的令牌和一个准备粘贴的配置块:```
[browser-mcp-lite] MCP server: http://127.0.0.1:12307/mcp
[browser-mcp-lite] WebSocket: ws://127.0.0.1:12307/ws
⚠ First run — new token generated
━━━ Auth Token (paste into Chrome Extension popup) ━━━
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
━━━ MCP Client Config (save as .mcp.json) ━━━
{
"mcpServers": {
"browser": {
"type": "http",
"url": "http://127.0.0.1:12307/mcp",
"headers": {
"Authorization": "Bearer "
}
}
}
}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[browser-mcp-lite] Waiting for Chrome Extension...
2.加载Chrome扩展程序
- 打开
chrome://extensions/ - 启用 开发人员模式 (右上)
- 点击 装载时未包装 → 选择
extension/文件夹 - 单击工具栏中的浏览器MCP Lite图标
- 复制终端中打印的令牌并将其粘贴到 授权令牌 领域
- 点击 连接
分机自动连接。单击工具栏图标以验证绿点。
3.连接您的AI助手
> 注: 准备粘贴 .mcp.json 服务器启动时,config会打印在终端中。
Claude Code
添加到您的项目 .mcp.json:```json
{
"mcpServers": {
"browser": {
"type": "http",
"url": "http://127.0.0.1:12307/mcp",
"headers": {
"Authorization": "Bearer YOUR_TOKEN_HERE"
}
}
}
}
替换 `YOUR_TOKEN_HERE` 令牌打印在终端中。
Claude Desktop
添加 `~/Library/Application Support/Claude/claude_desktop_config.json`:```json
{
"mcpServers": {
"browser": {
"type": "http",
"url": "http://127.0.0.1:12307/mcp",
"headers": {
"Authorization": "Bearer YOUR_TOKEN_HERE"
}
}
}
}
Cursor / VS Code
在光标中:设置→ MCP → 添加服务器:
- 姓名:
browser - 类型:
http - 网址:
http://127.0.0.1:12307/mcp - 标题:
Authorization: Bearer YOUR_TOKEN_HERE
建筑
三个组成部分```
┌─────────────────┐ ┌──────────────────┐ ┌──────────────────┐
│ AI Assistant │ │ MCP Server │ │ Chrome Extension │
│ (any MCP client) │────▶│ (Fastify) │────▶│ (Manifest V3) │
│ │HTTP │ :12307/mcp │ WS │ │
│ │POST │ Token auth │ │ tabs, scripting, │
│ │◀────│ │◀────│ activeTab, alarms │
└─────────────────┘ └──────────────────┘ └──────────────────┘
**MCP服务器** (`server/index.js`,约150行)
- 使用以下命令加速HTTP服务器 `@modelcontextprotocol/sdk` 可流式HTTP传输
- 对每个请求进行令牌身份验证(来自 `~/.browser-mcp-secrets.json`)
- Chrome扩展程序通信的WebSocket端点
- 每会话MCP传输管理
**Chrome 扩展** (`extension/background.js`,约215行)
- 清单V3服务工作者
- 带有保活警报的WebSocket客户端(在MV3 Service Worker终止后仍然有效)
- 通过Chrome API直接实现这四个工具
- 服务器重新启动时自动重新连接
**可访问性树生成器** (`extension/inject/accessibility-tree.js`,约195行)
- 注入目标页面以构建结构化DOM表示
- 输出 `ref_*` 每个交互/结构元素的ID
- 比原始HTML更具令牌效率——AI可以在不燃烧上下文的情况下推理页面结构
### 为什么使用可访问性树而不是原始HTML?
一个典型的网页有50-200KB的HTML。同一页面的可访问性树为2-10KB-- **小10-50x**。它去掉了样式、脚本和装饰元素,只保留了重要的东西:标题、链接、按钮、输入及其标签。```
# Raw HTML: ~150KB
Settings
# Accessibility tree: ~50 bytes
[ref_42 link "Settings" href=/settings]
安全性设计
- 令牌认证(两层):MCP端点需要
Authorization: BearerWebSocket端点要求在连接时进行令牌握手。两者都使用相同的令牌~/.browser-mcp-secrets.json. - 最低权限:只有
tabs,activeTab,scripting,alarms,storage不debugger,没有history,没有cookies,没有webRequest. - 仅限本地主机:服务器绑定到
127.0.0.1。未暴露于网络。 - 无网络代理:该扩展永远不会使用您的浏览器Cookie发出HTTP请求。它只读取DOM并截图。
- 手动扫描:需要时启动服务器,完成后按Ctrl+C。没有守护进程,没有自动启动。
- 可审计的:总共约500行。10分钟内读完。
保密考虑
> 注意你向你的人工智能助手暴露了什么。
list_tabs将所有打开的标签URL和标题发送给AI助手。如果你打开了敏感页面(电子邮件、医疗、私信),它们的网址和标题将可见。screenshot捕获屏幕上的任何内容,包括密码、个人数据或私人内容。screenshot切换选项卡:Chrome浏览器captureVisibleTabAPI只能捕获活动选项卡。如果截屏背景选项卡,它将被短暂切换到前台。
快速注射风险:恶意网页可能包含隐藏文本,诱使您的AI助手调用 inject_script 其他选项卡上有有害代码。在批准工具调用之前,请务必对其进行审查。不自动批准 inject_script 电话。
缓解措施:仅在需要时运行服务器。使用前请关闭敏感选项卡。查看您的AI助手可以通过以下方式查看的内容 list_tabs 在调用其他工具之前。切勿在MCP客户端中自动批准工具调用。
MV3服务人员生存
Chrome的Manifest V3会在大约30秒的不活动后终止Service Workers。该扩展使用 chrome.alarms 以24秒的间隔保持活动状态,并在需要时重新连接WebSocket。
定制
更改端口:```bash
MCP_PORT=9999 node index.js
在中更新WebSocket URL `extension/background.js` 第5行和 `extension/popup.html` 因此。
**添加新工具:**
编辑 `server/tools.js` 注册新的MCP工具,并在中添加相应的处理程序 `extension/background.js`s `handleToolRequest` 开关。
## 它是如何工作的(对于好奇的博客文章)
1. 启动MCP服务器(`node index.js`).它在听 `:12307` 用于HTTP(MCP)和WebSocket(扩展)。
1. Chrome扩展程序的Service Worker连接到 `ws://127.0.0.1:12307/ws`.
1. 您的AI助手发送MCP请求(例如。, `read_page`)to `http://127.0.0.1:12307/mcp` 持有Bearer代币。
1. 服务器验证令牌,将MCP调用转换为WebSocket消息,并将其发送到扩展。
1. 扩展执行对应的Chrome API调用(例如。, `chrome.scripting.executeScript` 注入可访问性树构建器)。
1. 结果返回:扩展→ 网络套接字→ 服务器→ http响应→ AI助手。
整个往返需要100-500ms,具体取决于页面的复杂性。
## 现实世界的例子
看 `examples/web-architectures.md` 了解从不同web架构读取数据的详细演练,这些架构包括基于iframe的传统门户、React/Angular SPA、Vue.js动态站点、AJAX密集型仪表板和CSP严格页面。
## 运行测试```bash
node --test tests/server.test.js
测试包括:健康检查、令牌认证(丢失/错误/有效)、MCP协议握手和会话管理。
文件结构```
browser-mcp-lite/
├── server/
│ ├── index.js # Fastify MCP Server + WebSocket hub
│ ├── tools.js # Tool schemas + handlers (4 tools)
│ ├── token.js # Shared token generation/loading
│ ├── setup.js # One-time token generator
│ └── package.json
├── extension/
│ ├── manifest.json # Manifest V3, minimal permissions
│ ├── background.js # Service Worker: WS client + tool implementations
│ ├── popup.html # Connection status UI
│ ├── popup.js
│ ├── inject/
│ │ └── accessibility-tree.js # DOM → structured text
│ └── icons/
├── examples/
│ └── web-architectures.md # Handling different web architectures
├── tests/
│ └── server.test.js # Server auth + protocol tests
├── LICENSE
├── README.md # English
└── README.zh-TW.md # 繁體中文
```
需求
- Node.js 18+
- Chrome或基于Chromium的浏览器
- 任何兼容MCP的AI客户端
许可证
麻省理工学院
学分
可访问性树方法的灵感来自 人向性/人向性流沙.
