内容
<a href="https://browsermcp.io">
<img src="./.github/images/banner.png" alt="Browser MCP banner">
</a>
<h3 align="center">Browser MCP</h3>
<p align="center">
使用人工智能自动化您的浏览器。
<br />
<a href="https://browsermcp.io"><strong>官方网站</strong></a>
•
<a href="https://docs.browsermcp.io"><strong>文档</strong></a>
</p>
## 关于
Browser MCP 是一个 MCP 服务器和浏览器扩展，允许您使用 VS Code、Claude、Cursor 和 Windsurf 等人工智能应用程序自动化浏览器。支持 **Chrome** 和 **Firefox**。
这是 [原始 Browser MCP](https://github.com/browsermcp/mcp) 的一个分支，具有以下更改：
- **独立构建**：所有 monorepo 依赖项（`@repo/*`，`@r2r/messaging`）替换为本地实现
- **扩展工具集**：39 个工具（从 12 个核心工具开始），包括标签管理、JavaScript 执行、cookie/storage 访问、CSS 注入、网络监控等
- **跨浏览器扩展**：具有所有 36 个命令处理器的功能齐全的扩展，兼容 Chrome（MV3）和 Firefox（MV3）
- **WSL 支持**：自动检测 WSL IP 并为扩展写入配置文件以发现正确的 WebSocket 地址
- **连接恢复**：工具描述中的速度指导，连接错误检测和重试提示
## 功能
- ⚡ 快速：自动化在您的机器上本地进行，从而在没有网络延迟的情况下获得更好的性能。
- 🔒 私有：由于自动化在本地进行，因此您的浏览器活动保留在您的设备上，不会发送到远程服务器。
- 👤 已登录：使用您现有的浏览器配置文件，让您保持登录到所有服务。
- 🥷🏼 隐身：通过使用您的真实浏览器指纹，避免基本的机器人检测和 CAPTCHA。
## 安装
### 先决条件
- Node.js >= 18
- Google Chrome, Chromium, 或 Firefox 113+
- Browser MCP 扩展（包含在 `extension/` 中）
### 从源代码构建
```bash
git clone https://github.com/IlGabbia998/browsermcp-mcp.git
cd browsermcp-mcp
npm install
npm run build
```
### 加载扩展
#### Chrome
1. 打开 Chrome 并导航到 `chrome://extensions`
2. 启用 **开发者模式**
3. 点击 **加载解压** 并选择此项目的 `extension/` 文件夹
4. 扩展程序将显示在您的工具栏中 - 点击它并在 MCP 服务器运行时点击 **重新连接**
#### Firefox
Firefox MV3 需要与 Chrome 不同的 `background` 条目。您必须在加载扩展之前切换清单。
使用帮助脚本（推荐）：
```bash
npm run use:firefox
```
或手动：
1. 将 `extension/manifest.firefox.json` 复制到 `extension/manifest.json`（替换 Chrome 的）
2. 打开 Firefox 并导航到 `about:debugging#/runtime/this-firefox`
3. 点击 **加载临时插件...**
4. 从此项目中选择 `extension/manifest.json`
5. 扩展程序将显示在您的工具栏中 - 点击它并在 MCP 服务器运行时点击 **连接**
> **注意：** Chrome 和 Firefox 使用不同的 MV3 清单格式。使用 `manifest.json` 表示 Chrome（默认），并运行 `npm run use:firefox`（或复制 `manifest.firefox.json`）表示 Firefox。Firefox 临时插件在 Firefox 重新启动时会被删除。要恢复 Chrome 清单，请运行 `npm run use:chrome`。
### 在您的 MCP 客户端中使用
将服务器添加到您的 MCP 客户端配置中。内置入口点为 `dist/index.js`。
#### Claude Desktop
编辑 `~/Library/Application Support/Claude/claude_desktop_config.json`（macOS）或 `%APPDATA%\Claude\claude_desktop_config.json`（Windows）：
```json
{
"mcpServers": {
"browser": {
"command": "node",
"args": ["/absolute/path/to/browsermcp-mcp/dist/index.js"]
}
}
}
```
#### opencode
将以下内容添加到您的 `opencode.json` 中：
```json
{
"mcp": {
"browser": {
"type": "local",
"command": ["node", "/absolute/path/to/browsermcp-mcp/dist/index.js"],
"enabled": true
}
}
}
```
#### Cursor / Windsurf
将以下内容添加到您的 MCP 设置中（`.cursor/mcp.json` 或等效）：
```json
{
"mcpServers": {
"browser": {
"command": "node",
"args": ["/absolute/path/to/browsermcp-mcp/dist/index.js"]
}
}
}
```
### 连接浏览器
1. 启动 MCP 服务器（通过您的 MCP 客户端或 `node dist/index.js`）
2. 打开 Chrome/Firefox 并点击工具栏中的 Browser MCP 扩展图标
3. 点击 **重新连接** - 扩展程序自动发现服务器地址
4. MCP 服务器将自动检测连接
## 可用工具（39）
### 核心
| 工具 | 描述 |
|------|-------------|
| `browser_navigate` | 导航到 URL |
| `browser_go_back` | 后退 |
| `browser_go_forward` | 前进 |
| `browser_snapshot` | 捕获页面的可访问性快照 |
| `browser_click` | 点击元素（按引用或描述） |
| `browser_hover` | 悬停在元素上 |
| `browser_type` | 在输入字段中输入文本 |
| `browser_select_option` | 在下拉菜单中选择选项 |
| `browser_drag` | 从一个元素拖动到另一个元素 |
| `browser_press_key` | 按键盘键 |
| `browser_wait` | 等待 N 秒 |
| `browser_screenshot` | 截取屏幕截图 |
| `browser_get_console_logs` | 获取浏览器控制台日志 |
### 导航和标签
| 工具 | 描述 |
|------|-------------|
| `browser_scroll` | 滚动页面（上/下/左/右） |
| `browser_new_tab` | 打开新标签 |
| `browser_reload` | 重新加载当前页面 |
| `browser_list_tabs` | 列出所有打开的标签 |
| `browser_close_tab` | 按 ID 关闭标签 |
| `browser_switch_tab` | 按 ID 切换到标签 |
### 页面交互
| 工具 | 描述 |
|------|-------------|
| `browser_find_text` | 在页面上查找文本内容 |
| `browser_execute_js` | 执行任意 JavaScript |
| `browser_get_links` | 从页面提取所有链接 |
| `browser_get_elements` | 按 CSS 选择器查询元素 |
| `browser_extract_table` | 以结构化 JSON 提取表格数据 |
| `browser_extract_meta` | 提取页面元数据和 OpenGraph 标签 |
| `browser_extract_images` | 从页面提取所有图像 |
| `browser_right_click` | 右键单击元素 |
| `browser_double_click` | 双击元素 |
| `browser_highlight` | 突出显示匹配选择器的元素 |
| `browser_readability` | 提取主要文章内容 |
| `browser_wait_for` | 等待元素出现 |
| `browser_get_computed_style` | 获取元素的计算 CSS 样式 |
| `browser_inject_css` | 将自定义 CSS 注入页面 |
### 存储和 Cookie
| 工具 | 描述 |
|------|-------------|
| `browser_get_cookies` | 获取当前页面的 Cookie |
| `browser_set_cookies` | 设置 Cookie |
| `browser_get_storage` | 从 localStorage 或 sessionStorage 读取 |
| `browser_set_storage` | 写入 localStorage 或 sessionStorage |
### 监控
| 工具 | 描述 |
|------|-------------|
| `browser_network_log` | 启动/停止/查询网络请求日志 |
| `browser_console_log` | 启动/停止/查询控制台日志拦截 |
## 使用示例
要求您的 AI 助手执行以下操作：
- “前往 github.com 并截取屏幕截图”
- “点击登录按钮并填写我的电子邮件”
- “向下滚动并点击下一页链接”
- “从此页面提取所有链接”
- “为此站点显示 Cookie”
- “运行 JavaScript 以获取页面标题”
- “在导航时监控网络请求”
- “在此页面上注入自定义 CSS 主题”
AI 使用可访问性快照来理解页面结构并可靠地与元素交互。
## 贡献
这是 Browser MCP 服务器的独立版本，从原始 monorepo 中提取。所有 monorepo 依赖项都已替换为本地实现。
### 项目结构
```
src/
index.ts # 入口点，工具注册
server.ts # 具有连接错误处理的 MCP 服务器
context.ts # WebSocket 上下文管理
ws.ts # WebSocket 服务器创建
lib/
config/ # 应用程序和 MCP 配置
messaging/ # WebSocket 消息发送者
types/ # 所有工具的 Zod 模式
tools/
snapshot.ts # 核心交互工具（点击，类型，悬停等）
common.ts # 导航工具（导航，后退等）
custom.ts # 截图，控制台日志
extended.ts # 所有扩展工具（26 个新工具）
tool.ts # 工具类型定义
utils/
port.ts # 端口实用程序
aria-snapshot.ts # 可访问性快照捕获
extension/
background.js # 跨浏览器服务工作者（36 个命令处理程序）
manifest.json # 扩展程序清单（MV3，Chrome + Firefox 兼容）
popup.html # 扩展程序弹出 UI
popup.js # 弹出 JavaScript
icons/ # 扩展程序图标
```
## 鸣谢
Browser MCP 改编自 [Playwright MCP 服务器](https://github.com/microsoft/playwright-mcp)，用于自动化用户浏览器而不是创建新的浏览器实例。这允许使用用户的现有浏览器配置文件来使用登录会话并避免通常阻止自动化浏览器使用的机器人检测机制。
