统一浏览器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：

{
  "mcpServers": {
    "unified-browser": {
      "command": "npx",
      "args": ["-y", "unified-browser-mcp"]
    }
  }
}

就是这样！ 当 Cursor 启动时，服务器将自动下载并运行。

注：你仍然需要一次性安装Playwright浏览器：

npx playwright install chromium

______________________________________________________________________

方法2：从源代码手动安装

如果您更倾向于从源代码构建或希望修改代码：

第一步：获取代码

选择以下方法之一：

选项A：从GitHub克隆

git clone https://github.com/msawayda/unified-browser-mcp.git
cd unified-browser-mcp

选项B：下载ZIP文件

访问 https://github.com/msawayda/unified-browser-mcp
点击“代码”→“下载ZIP文件”
提取到您选择的位置
在该文件夹中打开终端/命令提示符

步骤2：安装依赖项

npm install

这将安装：

@modelcontextprotocol/sdk - MCP通信层
playwright - 浏览器自动化库
TypeScript和构建工具

预期输出：

added 19 packages, and audited 20 packages in 25s
found 0 vulnerabilities

步骤3：构建服务器

npm run build

这个将TypeScript代码编译成JavaScript代码在 build/ 目录。

预期输出：

> unified-browser-mcp@1.0.0 build
> tsc

现在你应该能看到一个 build/ 带有文件夹的 index.js 里面。

步骤4：安装Playwright浏览器

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

添加服务器配置

打开配置文件 在文本编辑器中（如果不存在则创建一个）

添加您的服务器 到……的 mcpServers 对象：

对于npx安装（方法1）：

所有操作系统：

{
  "mcpServers": {
    "unified-browser": {
      "command": "npx",
      "args": ["-y", "unified-browser-mcp"]
    }
  }
}

简单！相同的配置适用于 Windows、macOS 和 Linux。

对于手动安装（方法2）：

Windows 示例：

{
  "mcpServers": {
    "unified-browser": {
      "command": "node",
      "args": [
        "C:\\Users\\YourUsername\\unified-browser-mcp\\build\\index.js"
      ]
    }
  }
}

macOS/Linux 示例：

{
  "mcpServers": {
    "unified-browser": {
      "command": "node",
      "args": [
        "/Users/yourusername/unified-browser-mcp/build/index.js"
      ]
    }
  }
}

重要注意事项：

✅ 使用 绝对路径 （从根目录开始的完整路径）
✅ 在Windows上，使用 双反斜杠 (\\) 或正斜杠 (/)
✅ 替换 YourUsername 使用你实际的用户名
✅ 将路径与您安装服务器的位置相匹配

如果您已经拥有其他MCP服务器在前一项之后加一个逗号：

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    },
    "unified-browser": {
      "command": "npx",
      "args": ["-y", "unified-browser-mcp"]
    }
  }
}

步骤5：重启Cursor/Claude桌面程序

重要提示： 您必须完全重启应用程序，以便MCP服务器加载。

完全关闭光标/关闭Claude桌面 （不仅仅是窗户）
重新打开应用程序
MCP服务器现在将在后台自动启动

它是如何工作的

自动服务器管理

当你启动 Cursor/Claude 桌面版时：

光标读取 你的 mcp.json 配置
启动服务器 通过运行： node path/to/build/index.js
建立沟通 通过 stdio（标准输入/输出）
保持其运转 在整个会话过程中都在后台运行
将其关闭 当你关闭 Cursor 时，它会自动（执行/完成等，具体动作需根据上下文确定）

你将在服务器日志（标准错误输出）中看到这一点：

Unified Browser MCP server running on stdio

使用服务器

一旦配置完成并重启Cursor：

开始对话 在Cursor中与Claude一起
这些工具自动可用 - 克劳德现在可以使用浏览器自动化命令
请求浏览器操作 比如：

- “打开浏览器并导航至example.com” - “填写此表格并监控网络请求” - “对当前页面进行截图”

克劳德将执行 在后台使用MCP工具

您永远无需手动启动或停止服务器！

验证

检查服务器是否成功加载

重启 Cursor 后，您可以验证服务器是否正常运行：

与克劳德开始新对话
问： “你们有哪些可用的MCP工具？”
寻找： 像……这样的工具 launch_browser， navigate， start_monitoring等。

如果你看到这些工具，说明服务器运行正常！ ✅

常见的安装问题

❌“找不到模块 '@modelcontextprotocol/sdk'”

问题： 未安装的依赖项

解决方案：

cd unified-browser-mcp
npm install

❌ “未找到 build/index.js”

问题： TypeScript 未编译

解决方案：

npm run build

❌“未找到 Playwright 浏览器”

问题： 未下载Chromium

解决方案：

npx playwright install chromium

❌ 工具未在Claude中显示

可能的原因：

mcp.json 中的路径错误 - 再次核对绝对路径
没有重启Cursor - 必须完全重启，而不仅仅是重新加载窗口
JSON语法错误 - 在 https://jsonlint.com/ 验证您的 JSON
文件位置错误 - 配置文件必须位于操作系统特定的正确位置

调试步骤：

检查 Cursor 的开发者控制台（帮助 → 切换开发者工具）
查找与MCP相关的错误
验证路径是否存在： node C:\path\to\build\index.js 应输出服务器消息

正在更新

在拉取新更改后更新服务器：

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 （字符串，必填）：要导航到的URL
waitUntil （字符串，可选）：何时视为导航完成

- 选项： 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

2. navigate
   - url: "https://example.com/contact"

3. start_monitoring
   - clearPrevious: true

4. fill_form_field
   - selector: "#name"
   - value: "John Doe"

5. fill_form_field
   - selector: "#email"
   - value: "john@example.com"

6. submit_form
   - selector: "#submit"

7. get_network_requests
   - filter: "api"

8. get_console_messages
   - type: "error"

9. get_performance_metrics

10. 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响应（二进制数据被跳过）
如果请求尚未完成，某些响应可能不可用

发展

做出更改后进行重建：

npm run build

TypeScript 编译器将输出到 build/ 目录。

许可证

麻省理工学院（MIT）

Unified Browser MCP

快速接入

详细介绍

统一浏览器MCP服务器

特点/特性

什么是MCP服务器？

安装

先决条件

方法1：使用npx（推荐 - 最简单）

方法2：从源代码手动安装

配置

找到您的MCP配置文件

添加服务器配置

对于npx安装（方法1）：

对于手动安装（方法2）：

步骤5：重启Cursor/Claude桌面程序

它是如何工作的

自动服务器管理

使用服务器

验证

检查服务器是否成功加载

常见的安装问题

❌“找不到模块 '@modelcontextprotocol/sdk'”

❌ “未找到 build/index.js”

❌“未找到 Playwright 浏览器”

❌ 工具未在Claude中显示

正在更新

可用工具

浏览器生命周期

launch_browser

close_browser

导航与自动化

navigate

fill_form_field

click_element

submit_form

screenshot

evaluate_script

监控与开发工具

start_monitoring

get_network_requests

get_console_messages

get_performance_metrics

stop_monitoring

示例用法

用例

利用网络监控实现表单自动化

性能测试

调试Web应用程序

集成测试

技术细节

故障排除

浏览器无法启动

“浏览器未启动”错误

网络请求缺失

响应体为空

发展

许可证

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP

`launch_browser`

`close_browser`

`navigate`

`fill_form_field`

`click_element`

`submit_form`

`screenshot`

`evaluate_script`

`start_monitoring`

`get_network_requests`

`get_console_messages`

`get_performance_metrics`

`stop_monitoring`