统一浏览器MCP服务器
一个模型上下文协议(MCP)服务器,它在一个浏览器实例中集成了Playwright浏览器自动化与DevTools风格的监控功能。
特点/特性
- 浏览器自动化导航、填写表单、点击元素、截取屏幕截图
- 网络监控捕获所有网络请求,包括完整头部和响应体
- 控制台日志记录监控所有控制台消息(日志、警告、错误、信息)
- 性能指标提取导航时间API数据
- 单个浏览器实例所有操作都在同一个浏览器/页面上进行,以确保一致性
什么是MCP服务器?
模型上下文协议(MCP)允许像Claude这样的AI助手与外部工具和服务进行交互。这个MCP服务器充当Claude与浏览器自动化功能之间的桥梁,每当您使用Claude Desktop或Cursor时,它都会在后台自动运行。
要点:
- 🔄 旋转或循环的符号(注:此符号本身无直接对应中文含义,常用于表示旋转、循环、重复等概念) 自动启动当你打开 Cursor/Claude Desktop 时,服务器会自动启动
- 🔌 电源插头 无需手动运行你永远不需要手动启动服务器
- 🛠️(扳手或工具的象征,常用于表示需要动手操作或维修) 工具提供商为Claude提供浏览器自动化工具
- 💬 交流使用JSON-RPC通过标准输入输出与Claude通信
安装
先决条件
在安装之前,请确保您已具备:
- Node.js (v18 或更高版本) - 在此下载
- 光标 或者 Claude Desktop(可译为“Claude桌面版”或保持原样,根据上下文判断是否需要具体化为“Claude桌面应用程序”等) - 下载 Cursor
方法1:使用npx(推荐 - 最简单)
这是最简单的方法 - 无需克隆,无需构建,只需一次配置更新!
只需将此添加到您的MCP配置文件中,然后重启Cursor:```json
{
"mcpServers": {
"unified-browser": {
"command": "npx",
"args": ["-y", "unified-browser-mcp"]
}
}
}
**就是这样!** 当 Cursor 启动时,服务器将自动下载并运行。
**注:** 你仍然需要一次性安装Playwright浏览器:```bash
npx playwright install chromium
方法2:从源代码手动安装
如果您更倾向于从源代码构建或希望修改代码:
第一步:获取代码
选择以下方法之一:
选项A:从GitHub克隆```bash
git clone https://github.com/msawayda/unified-browser-mcp.git
cd unified-browser-mcp
**选项B:下载ZIP文件**
1. 访问 https://github.com/msawayda/unified-browser-mcp
1. 点击“代码”→“下载ZIP文件”
1. 提取到您选择的位置
1. 在该文件夹中打开终端/命令提示符
**步骤2:安装依赖项**```bash
npm install
这将安装:
@modelcontextprotocol/sdk- MCP通信层playwright- 浏览器自动化库- TypeScript和构建工具
预期输出:```
added 19 packages, and audited 20 packages in 25s
found 0 vulnerabilities
**步骤3:构建服务器**```bash
npm run build
这个将TypeScript代码编译成JavaScript代码在 build/ 目录。
预期输出:```
> unified-browser-mcp@1.0.0 build
> tsc
现在你应该能看到一个 `build/` 带有文件夹的 `index.js` 里面。
**步骤4:安装Playwright浏览器**```bash
npx playwright install chromium
这将下载Playwright将使用的Chromium浏览器(约150 MB)。
预期输出:```
Downloading Chromium 141.0.7390.37...
Chromium downloaded to C:\Users[username]\AppData\Local\ms-playwright\chromium-1194
**注:** 每台机器只需执行一次此操作。
## 配置
### 找到您的MCP配置文件
MCP配置文件的位置取决于您的操作系统:
| 操作系统 | 配置文件路径 |
|---|---|
| **Windows** | `C:\Users\[username]\.cursor\mcp.json` |
| **macOS(发音:/ˈmækɒs/)** | `~/Library/Application Support/Cursor/mcp.json` |
| **Linux** | `~/.config/cursor/mcp.json` |
**对于Claude Desktop** (而非光标):
- **Windows**: `C:\Users\[username]\AppData\Roaming\Claude\mcp.json`
- **macOS**: `~/Library/Application Support/Claude/mcp.json`
- **Linux**: `~/.config/Claude/mcp.json`
### 添加服务器配置
1. **打开配置文件** 在文本编辑器中(如果不存在则创建一个)
1. **添加您的服务器** 到……的 `mcpServers` 对象:
#### 对于npx安装(方法1):
**所有操作系统:**```json
{
"mcpServers": {
"unified-browser": {
"command": "npx",
"args": ["-y", "unified-browser-mcp"]
}
}
}
简单!相同的配置适用于 Windows、macOS 和 Linux。
对于手动安装(方法2):
Windows 示例:```json
{
"mcpServers": {
"unified-browser": {
"command": "node",
"args": [
"C:\Users\YourUsername\unified-browser-mcp\build\index.js"
]
}
}
}
**macOS/Linux 示例:**```json
{
"mcpServers": {
"unified-browser": {
"command": "node",
"args": [
"/Users/yourusername/unified-browser-mcp/build/index.js"
]
}
}
}
重要注意事项:
- ✅ 使用 绝对路径 (从根目录开始的完整路径)
- ✅ 在Windows上,使用 双反斜杠 (
\\) 或正斜杠 (/) - ✅ 替换
YourUsername使用你实际的用户名 - ✅ 将路径与您安装服务器的位置相匹配
- 如果您已经拥有其他MCP服务器在前一项之后加一个逗号:```json
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": ["@playwright/mcp@latest"]
},
"unified-browser": {
"command": "npx",
"args": ["-y", "unified-browser-mcp"]
}
}
}
### 步骤5:重启Cursor/Claude桌面程序
**重要提示:** 您必须完全重启应用程序,以便MCP服务器加载。
1. **完全关闭光标/关闭Claude桌面** (不仅仅是窗户)
1. **重新打开应用程序**
1. MCP服务器现在将在后台自动启动
## 它是如何工作的
### 自动服务器管理
当你启动 Cursor/Claude 桌面版时:
1. **光标读取** 你的 `mcp.json` 配置
1. **启动服务器** 通过运行: `node path/to/build/index.js`
1. **建立沟通** 通过 stdio(标准输入/输出)
1. **保持其运转** 在整个会话过程中都在后台运行
1. **将其关闭** 当你关闭 Cursor 时,它会自动(执行/完成等,具体动作需根据上下文确定)
你将在服务器日志(标准错误输出)中看到这一点:```
Unified Browser MCP server running on stdio
使用服务器
一旦配置完成并重启Cursor:
- 开始对话 在Cursor中与Claude一起
- 这些工具自动可用 - 克劳德现在可以使用浏览器自动化命令
- 请求浏览器操作 比如:
- “打开浏览器并导航至example.com”
- “填写此表格并监控网络请求”
- “对当前页面进行截图” - 克劳德将执行 在后台使用MCP工具
您永远无需手动启动或停止服务器!
验证
检查服务器是否成功加载
重启 Cursor 后,您可以验证服务器是否正常运行:
- 与克劳德开始新对话
- 问: “你们有哪些可用的MCP工具?”
- 寻找: 像……这样的工具
launch_browser,navigate,start_monitoring等。
如果你看到这些工具,说明服务器运行正常! ✅
常见的安装问题
❌“找不到模块 '@modelcontextprotocol/sdk'”
问题: 未安装的依赖项
解决方案:```bash
cd unified-browser-mcp
npm install
#### ❌ “未找到 build/index.js”
**问题:** TypeScript 未编译
**解决方案:**```bash
npm run build
❌“未找到 Playwright 浏览器”
问题: 未下载Chromium
解决方案:```bash
npx playwright install chromium
#### ❌ 工具未在Claude中显示
**可能的原因:**
1. **mcp.json 中的路径错误** - 再次核对绝对路径
1. **没有重启Cursor** - 必须完全重启,而不仅仅是重新加载窗口
1. **JSON语法错误** - 在 https://jsonlint.com/ 验证您的 JSON
1. **文件位置错误** - 配置文件必须位于操作系统特定的正确位置
**调试步骤:**
1. 检查 Cursor 的开发者控制台(帮助 → 切换开发者工具)
1. 查找与MCP相关的错误
1. 验证路径是否存在: `node C:\path\to\build\index.js` 应输出服务器消息
## 正在更新
在拉取新更改后更新服务器:```bash
cd unified-browser-mcp
git pull origin main # If using git
npm install # Install any new dependencies
npm run build # Rebuild
然后重启 Cursor/Claude 桌面应用。
可用工具
浏览器生命周期
launch_browser
启动一个新的Chromium浏览器实例。
参数:
headless(布尔值,可选):以无头模式运行(默认:false)viewport(对象,可选):设置视口大小width(数字): 视口宽度(默认:1280)height(数字):视口高度(默认:720)
close_browser
关闭浏览器并清理所有资源。
导航与自动化
navigate
导航到一个URL。
参数:
url(字符串,必填):要导航到的URLwaitUntil(字符串,可选):何时视为导航完成- 选项:
load,domcontentloaded,networkidle - 默认:
load
fill_form_field
在表单字段中填入一个值。
参数:
selector(字符串,必填):表单字段的CSS选择器value(字符串,必填):要填充的值
click_element
点击页面上的一个元素。
参数:
selector(字符串,必需): 元素的CSS选择器waitForNavigation(布尔值,可选):点击后等待导航(默认:false)
submit_form
通过点击提交按钮或表单元素来提交表单。
参数:
selector(字符串,必需):提交按钮或表单的CSS选择器
screenshot
对页面或特定元素进行截图。
参数:
fullPage(布尔值,可选):捕获可滚动的完整页面(默认:false)selector(字符串,可选):用于截取特定元素的CSS选择器
evaluate_script
在页面上下文中执行JavaScript代码。
参数:
script(字符串,必需):要执行的 JavaScript 代码
监控与开发工具
start_monitoring
开始捕获网络请求和控制台消息。
参数:
clearPrevious(布尔值,可选):清除之前捕获的数据(默认:true)
get_network_requests
获取所有捕获的网络请求的完整详细信息。
参数:
filter(字符串,可选):按URL模式过滤请求
返回值: 包含以下内容的网络请求数组:
- URL(统一资源定位符),方法,时间戳
- 请求头和POST数据
- 响应状态、头部和正文(仅限文本/JSON)
get_console_messages
获取所有捕获的控制台消息。
参数:
type(字符串,可选):按消息类型过滤- 选项:
log,warning,error,info,all - 默认:
all
get_performance_metrics
从导航定时API中获取页面性能指标。
返回值: 性能计时数据包括:
- DOM 内容加载时间
- 加载完成时间
- DOM交互时间
- DNS、TCP、请求和响应时间
stop_monitoring
停止监控并返回捕获数据的摘要。
返回值: 总结,包含总数及按状态/类型细分的统计
示例用法
以下是一个典型的自动化表单提交并同时监控网络活动的工作流程:```
1. launch_browser
- headless: false
-
navigate
- url: "https://example.com/contact" -
start_monitoring
- clearPrevious: true -
fill_form_field
- selector: "#name"
- value: "John Doe" -
fill_form_field
- selector: "#email"
- value: "john@example.com" -
submit_form
- selector: "#submit" -
get_network_requests
- filter: "api" -
get_console_messages
- type: "error" -
get_performance_metrics
-
close_browser
## 用例
### 利用网络监控实现表单自动化
在捕获所有API调用、XHR请求和响应的同时,自动化表单提交。
### 性能测试
导航至各个页面并收集详细的性能指标,包括时间数据。
### 调试Web应用程序
在自动化交互过程中监控控制台错误和网络故障。
### 集成测试
验证表单是否触发了正确的API调用,并附带了适当的负载和响应。
## 技术细节
- **浏览器引擎**通过Playwright的Chromium(浏览器)
- **沟通**通过标准输入输出进行JSON-RPC通信(MCP标准)
- **网络捕获**完整的请求/响应周期,包括头部和主体
- **控制台捕获**所有带有时间戳和位置的消息类型
- **单实例**一个浏览器/上下文/页面在所有操作中共享
## 故障排除
### 浏览器无法启动
- 确保已安装 Playwright 浏览器: `npx playwright install chromium`
- 检查 Node.js 是否已添加到你的系统路径中
### “浏览器未启动”错误
- 随时致电 `launch_browser` 在其他操作之前
- 如果浏览器崩溃,请拨打 `launch_browser` 再次
### 网络请求缺失
- 呼叫 `start_monitoring` 在导航/交互之前
- 网络捕获在……之后开始 `start_monitoring` 被称为
### 响应体为空
- 仅捕获文本和JSON响应(二进制数据被跳过)
- 如果请求尚未完成,某些响应可能不可用
## 发展
做出更改后进行重建:```bash
npm run build
TypeScript 编译器将输出到 build/ 目录。
许可证
麻省理工学院(MIT)