浏览器代理 MCP

MCP 浏览器代理

特征

高级浏览器自动化
- 使用可自定义的加载策略导航到任何 URL
- 捕获整页或特定元素的屏幕截图
- 执行精确的 DOM 交互（单击、填充、选择、悬停）
- 使用控制台日志捕获在浏览器上下文中执行任意 JavaScript
强大的API客户端
- 执行 HTTP 请求（GET、POST、PUT、PATCH、DELETE）
- 配置请求标头和正文内容
- 使用 JSON 格式处理响应数据
- 带有详细反馈的错误处理
MCP资源管理
- 将浏览器控制台日志作为资源进行访问
- 通过MCP资源接口获取截图
- 与 headful 浏览器实例的持久会话
AI代理功能
- 链接多个浏览器操作以完成复杂任务
- 遵循多步骤指令，智能错误恢复
- 通过自然语言指令实现技术任务自动化

演示

点击任意时间戳即可跳转到视频的相应部分

00:00 - Google 搜索 MCP
导航到 Google 主页并搜索“模型上下文协议”。演示如何使用 MCP 集成执行基本的网页搜索并处理结果。

00:33 -截图
使用自定义文件名截取搜索结果的屏幕截图，并在 Finder 中展示。展示了 Claude 如何在浏览器自动化过程中捕获并保存网页中的视觉内容。

01:00 -维基百科搜索
导航到 Wikipedia.org 并搜索“模型上下文协议”。演示了 Claude 通过 MCP 集成与不同网站及其搜索功能进行交互的能力。

01:38 -下拉菜单交互 I
导航到测试网站 (the-internet.herokuapp.com/dropdown) 并从下拉菜单中选择“选项 1”。演示了 Claude 与表单元素交互并进行选择的能力。

01:56 -下拉菜单交互 II
从同一个下拉菜单中将选项更改为“选项 2”。这展现了 Claude 能够多次操作同一表单元素并做出不同选择的能力。

02:09 -登录表单完成
导航到登录页面 (the-internet.herokuapp.com/login)，并在用户名字段中填写“tomsmith”，在密码字段中填写“SuperSecretPassword!”。演示了表单填写的自动化。

02:28 -登录提交
提交登录凭证并完成身份验证过程。展示了 Claude 触发表单提交和浏览多步骤流程的能力。

02:36 - API 请求执行
向 JSONPlaceholder API 端点执行 GET 请求。演示了 Claude 能够直接调用 API 并通过 MCP 集成处理返回的数据。

要求

Node.js 16 或更高版本
克劳德桌面
剧作家依赖关系

浏览器支持

npm init playwright@latest

此软件包包含 Playwright 以及运行浏览器自动化所需的依赖项。运行npm install时，将安装所需的 Playwright 依赖项。此软件包支持以下浏览器：

Chrome（默认）
火狐
微软 Edge
WebKit（Safari 引擎）

首次使用某种浏览器类型时，Playwright 会根据需要自动安装相应的浏览器驱动程序。您也可以使用以下命令手动安装：

npx playwright install chrome
npx playwright install firefox
npx playwright install webkit
npx playwright install msedge

关于 Safari 的说明：Playwright 不直接支持 Safari 浏览器。相反，它使用 WebKit，它是驱动 Safari 的浏览器引擎。
关于 Edge 的注意事项：选择 Edge 作为浏览器类型时，代理实际上会启动 Microsoft Edge（而非 Chromium）。从技术上讲，在 Playwright 中，Edge 是使用 Chromium 浏览器实例和“msedge”通道参数启动的，因为 Microsoft Edge 基于 Chromium。

安装

手动安装

克隆或下载此存储库：

git clone https://github.com/imprvhub/mcp-browser-agent
cd mcp-browser-agent

安装依赖项：

npm install

构建项目：

npm run build

运行 MCP 服务器

运行 MCP 服务器有两种方式：

选项 1：手动运行

打开终端或命令提示符
导航到项目目录
直接运行服务器：

node dist/index.js

使用 Claude Desktop 时，请保持此终端窗口打开。服务器将一直运行，直到您关闭终端。

选项 2：使用 Claude Desktop 自动启动（建议定期使用）

Claude Desktop 可以在需要时自动启动 MCP 服务器。设置方法如下：

配置

Claude Desktop 配置文件位于：

macOS ： ~/Library/Application Support/Claude/claude_desktop_config.json
Windows ： %APPDATA%\Claude\claude_desktop_config.json
Linux ： ~/.config/Claude/claude_desktop_config.json

编辑此文件以添加浏览器代理 MCP 配置。如果该文件不存在，请创建它：

{
  "mcpServers": {
    "browserAgent": {
      "command": "node",
      "args": ["ABSOLUTE_PATH_TO_DIRECTORY/mcp-browser-agent/dist/index.js",
      "--browser",
      "chrome"
    ]
    }
  }
}

重要提示：将ABSOLUTE_PATH_TO_DIRECTORY替换为您安装 MCP 的完整绝对路径

macOS/Linux 示例： /Users/username/mcp-browser-agent
Windows 示例： C:\\Users\\username\\mcp-browser-agent

如果您已配置其他 MCP，只需在“mcpServers”对象中添加“browserAgent”部分即可。以下是包含多个 MCP 的配置示例：

{
  "mcpServers": {
    "otherMcp1": {
      "command": "...",
      "args": ["..."]
    },
    "otherMcp2": {
      "command": "...",
      "args": ["..."]
    },
    "browserAgent": {
      "command": "node",
      "args": [
        "ABSOLUTE_PATH_TO_DIRECTORY/mcp-browser-agent/dist/index.js",
      "--browser",
      "chrome"
    ]
    }
  }
}

浏览器选择

MCP 浏览器代理支持多种浏览器类型。默认情况下，它使用 Chrome，但您可以通过多种方式指定其他浏览器：

选项 1：配置文件

在您的主目录中创建或编辑文件.mcp_browser_agent_config.json ：

{
  "browserType": "chrome"
}

browserType支持的值为：

chrome - 使用已安装的 Chrome（默认）
firefox - 使用 Firefox Nightly 浏览器
webkit - 使用 WebKit 引擎（注意：这不是 Safari 本身，而是为 Safari 提供支持的 WebKit 渲染引擎）
edge - 使用 Microsoft Edge

关于 Safari 的说明：Playwright 不直接支持 Safari 浏览器。它使用的是 WebKit，它是驱动 Safari 的浏览器引擎。Playwright 中的 WebKit 实现提供了类似的功能，但体验与 Safari 浏览器并不完全相同。

选项 2：命令行参数

手动启动 MCP 服务器时，可以指定浏览器类型：

node dist/index.js --browser firefox

选项 3：环境变量

设置MCP_BROWSER_TYPE环境变量：

MCP_BROWSER_TYPE=firefox node dist/index.js

选项 4：Claude 桌面配置

在 Claude Desktop 的claude_desktop_config.json中配置 MCP 时，可以指定浏览器类型：

{
  "mcpServers": {
    "browserAgent": {
      "command": "node",
      "args": [
        "ABSOLUTE_PATH_TO_DIRECTORY/mcp-browser-agent/dist/index.js",
        "--browser",
        "chrome"
      ]
    }
  }
}

技术实现

MCP 浏览器代理基于模型上下文协议 (MCP Protocol) 构建，使 Claude 能够通过 Playwright 与 Headful 浏览器进行交互。该实现包含四个主要组件：

服务器（index.ts）
- 使用模型上下文协议标准协议初始化 MCP 服务器
- 配置工具和资源的服务器功能
- 通过 stdio 传输与 Claude 建立通信
工具注册表（tools.ts）
- 定义浏览器和 API 工具模式
- 指定参数、验证规则和说明
- 向 MCP 服务器注册工具，用于 Claude 的发现
请求处理程序（handlers.ts）
- 管理工具和资源的 MCP 协议请求
- 将浏览器日志和屏幕截图公开为可查询的资源
- 将工具执行请求路由到适当的处理程序
执行器（executor.ts）
- 管理浏览器和 API 客户端生命周期
- 使用 Playwright 实现浏览器自动化功能
- 使用适当的错误处理和响应解析来处理 API 请求
- 在命令之间维护有状态的浏览器会话

代理能力

与基本集成不同，MCP 浏览器代理通过以下方式充当真正的 AI 代理：

在多个命令之间保持持久浏览器状态
捕获详细的控制台日志以进行调试
保存屏幕截图以供参考和审查
管理复杂的交互序列
提供详细的错误信息以便恢复
支持复杂工作流程的链式操作

可用工具

浏览器工具

工具名称	描述	参数
`browser_navigate`	导航到 URL	`url` （必需）、 `timeout` 、 `waitUntil`
`browser_screenshot`	截取屏幕截图	`name` （必需）、 `selector` 、 `fullPage` 、 `mask` 、 `savePath`
`browser_click`	单击元素	`selector` （必需）
`browser_fill`	填写表单输入	`selector` （必需）， `value` （必需）
`browser_select`	选择下拉选项	`selector` （必需）， `value` （必需）
`browser_hover`	将鼠标悬停在元素上	`selector` （必需）
`browser_evaluate`	执行 JavaScript	`script` （必需）

API 工具

工具名称	描述	参数
`api_get`	GET 请求	`url` （必需）、 `headers`
`api_post`	POST 请求	`url` （必需）、 `data` （必需）、 `headers`
`api_put`	PUT 请求	`url` （必需）、 `data` （必需）、 `headers`
`api_patch`	PATCH 请求	`url` （必需）、 `data` （必需）、 `headers`
`api_delete`	删除请求	`url` （必需）、 `headers`

资源访问

MCP 浏览器代理公开以下资源：

browser://logs - 访问浏览器控制台日志
screenshot://[name] - 通过名称访问截图

示例用法

以下是一些如何将 MCP 浏览器代理与 Claude 结合使用的实际示例：

基本浏览器导航

Navigate to the Google homepage at https://www.google.com

Take a screenshot of the current page and name it "google-homepage"

Type "weather forecast" in the search box

简单交互

Navigate to https://www.wikipedia.org and search for "Model Context Protocol"

Go to https://the-internet.herokuapp.com/dropdown and select the option "Option 1" from the dropdown

基本表格填写

Navigate to https://the-internet.herokuapp.com/login and fill in the username field with "tomsmith" and the password field with "SuperSecretPassword!"

Go to https://the-internet.herokuapp.com/login, fill in the username and password fields, then click the login button

简单的 JavaScript 执行

Go to https://example.com and execute a JavaScript script to return the page title

Navigate to https://www.google.com and execute a JavaScript script to count the number of links on the page

基本 API 请求

Perform a GET request to https://jsonplaceholder.typicode.com/todos/1

Make a POST request to https://jsonplaceholder.typicode.com/posts with appropriate JSON data

这些示例代表了 MCP 浏览器代理的实际功能，并且更现实地说明了它在当前状态下可以完成的任务。

故障排除

“服务器断开连接”错误

如果您在 Claude Desktop 中看到错误“MCP 浏览器代理：服务器已断开连接”：

验证服务器正在运行：
- 打开终端并从项目目录手动运行node dist/index.js
- 如果服务器启动成功，则使用 Claude 并保持此终端打开
检查您的配置：
- 确保claude_desktop_config.json中的绝对路径对于您的系统来说是正确的
- 仔细检查 Windows 路径是否使用了双反斜杠 ( \\ )
- 验证您使用的文件系统根目录的完整路径

浏览器未显示

如果浏览器没有启动或者您没有看到它：

检查指定的浏览器是否已安装
- 验证您的系统上是否安装了浏览器（Chrome、Firefox、Edge 或 Safari/WebKit）
- 浏览器驱动程序由 Playwright 自动处理
重启服务器和 Claude Desktop
- 终止可能正在运行服务器的任何现有节点进程
- 重新启动 Claude Desktop 以建立新的连接

浏览器进程未正确关闭

Chromium 和 Chrome 浏览器存在已知问题，在使用后进程有时无法正常终止。如果您遇到此问题：

手动关闭浏览器进程：
- Windows ：按 Ctrl+Shift+Esc 打开任务管理器，找到 Chrome/Chromium 进程并结束它
- macOS ：打开活动监视器（应用程序 > 实用程序 > 活动监视器），找到 Chrome/Chromium 进程并单击 X 将其终止
- Linux ：运行ps aux | grep chrome或ps aux | grep chromium来查找进程，然后kill <PID>终止它
关于浏览器兼容性的注意事项：
- 此问题主要出现在 Chromium 和 Chrome 中
- Firefox 和 Playwright 的内置浏览器通常不会遇到此问题

注意：此 MCP 集成基于 Playwright 构建，Playwright 存在已知问题和错误，可能会影响其运行。请将您在浏览器自动化过程中遇到的任何问题报告至Playwright 的 GitHub 问题。Playwright 团队正在持续努力解决这些问题，但尽管存在这些限制，此代理仍为 Claude Desktop 的浏览器自动化功能奠定了基础。

发展

项目结构

src/index.ts ：主入口点和 MCP 服务器初始化
src/tools.ts ：工具模式和注册
src/handlers.ts ：工具和资源的 MCP 请求处理程序
src/executor.ts ：使用 Playwright 的工具实现逻辑

建筑

npm run build

观察变化

npm run watch

测试

该项目包括验证核心功能和浏览器处理的测试。

npm test               # Run tests
npm run test:watch     # Watch mode
npm run test:coverage  # Coverage report

测试验证配置完整性、浏览器自动化功能、错误处理和进程清理。由于 Chrome/Chromium 终止存在已知问题，该测试套件尤其侧重于确保浏览器进程的正确处理。

安全注意事项

重要提示：此 MCP 集成为 Claude 提供了自主浏览器控制功能。请查看我们的安全政策，了解有关禁止使用、安全隐患和最佳实践的重要信息。

MCP 浏览器代理旨在执行合法的自动化任务，但也可能被滥用。用户有责任确保其使用符合所有适用法律、服务条款和道德准则。请参阅我们详细的安全政策，了解更多信息。

贡献

欢迎为 MCP 浏览器代理做出贡献！以下是您可以提供帮助的领域：

添加新的浏览器自动化功能
改进错误处理和恢复
增强屏幕截图和资源管理
创建有用的工作流程和示例
优化复杂操作的性能

执照

该项目根据 Mozilla 公共许可证 2.0 获得许可 - 有关详细信息，请参阅LICENSE文件。