MCP 浏览器代理

这是一个强大的 Model Context Protocol (MCP) 集成，为 Claude Desktop 提供了自主浏览器自动化功能。

功能

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

演示

时间戳:

点击任一时间戳跳转至视频相应部分

00:00 - Google 搜索 MCP
导航至 Google 主页并搜索 "Model Context Protocol"。展示 Claude Desktop 如何使用 MCP 集成执行基本网页搜索并处理结果。

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

01:00 - Wikipedia 搜索
导航至 Wikipedia.org 并搜索 "Model Context Protocol"。说明 Claude 通过 MCP 集成与不同网站及其搜索功能互动的能力。

01:38 - 下拉菜单交互 I
导航至测试网站 (the-internet.herokuapp.com/dropdown)，并从下拉菜单中选择 "Option 1"。展示了 Claude 与表单元素交互并做出选择的能力。

01:56 - 下拉菜单交互 II
将选择更改为同一下拉菜单中的 "Option 2"。展示了 Claude 多次操作同一表单元素并做出不同选择的能力。

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

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

[**02:36**](https://www.youtube.com/watch?v=0lMsKiTy7TE&t=156s) - **API 请求执行** 向 JSONPlaceholder API 端点执行 GET 请求。演示了 Claude 通过 MCP 集成直接进行 API 调用并处理返回数据的能力。

要求

Node.js 16 或更高版本
Claude 桌面版
Playwright 依赖项

浏览器支持

bash npm init playwright@latest

此包包括 Playwright 及运行浏览器自动化所需的必要依赖项。当你运行 npm install 时，将安装所需的 Playwright 依赖项。该包支持以下浏览器：

Chrome（默认）
Firefox
Microsoft 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 是通过带有 msedge 通道参数的 Chromium 浏览器实例启动的，因为 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 桌面版时，请保持此终端窗口打开。服务器将一直运行，直到你关闭终端。

选项 2：与 Claude 桌面版一起自动启动（推荐用于常规使用）

Claude 桌面版可以在需要时自动启动 MCP 服务器。要设置这一点：

配置

Claude 桌面版配置文件位于：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%Claudeclaude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

编辑此文件以添加 Browser Agent MCP 配置。如果文件不存在，请创建它：

json { "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 的示例：

json { "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 文件：

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 时，可以指定浏览器类型：

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

技术实现

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

服务器 (index.ts)
- 使用 Model Context Protocol 标准协议初始化 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`	DELETE 请求	`url`（必需），`headers`

资源访问

MCP 浏览器代理公开以下资源：- browser://logs - 访问浏览器控制台日志

screenshot://[name] - 按名称访问屏幕截图

示例用法

以下是一些使用MCP浏览器代理与Claude的现实示例：

基本浏览器导航

导航到Google主页 https://www.google.com

对当前页面进行截图并命名为 "google-homepage"

在搜索框中输入 "weather forecast"

简单交互

导航到 https://www.wikipedia.org 并搜索 "Model Context Protocol"

前往 https://the-internet.herokuapp.com/dropdown 并从下拉菜单中选择 "Option 1"

基本表单填写

导航到 https://the-internet.herokuapp.com/login 并在用户名字段中填写 "tomsmith"，密码字段中填写 "SuperSecretPassword!"

前往 https://the-internet.herokuapp.com/login，填写用户名和密码字段，然后点击登录按钮

简单JavaScript执行

前往 https://example.com 并执行一个JavaScript脚本来返回页面标题

导航到 https://www.google.com 并执行一个JavaScript脚本来计算页面上的链接数量

基本API请求

向 https://jsonplaceholder.typicode.com/todos/1 发送GET请求

向 https://jsonplaceholder.typicode.com/posts 发送带有适当JSON数据的POST请求

这些示例代表了MCP浏览器代理的实际功能，并更真实地反映了其当前状态下的能力。

故障排除

"服务器断开连接" 错误

如果您在Claude Desktop中看到错误 "MCP Browser Agent: Server disconnected"：

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

浏览器未出现

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

检查指定的浏览器是否已安装
- 确认您的系统上已安装浏览器（Chrome、Firefox、Edge 或 Safari/WebKit）
- 浏览器驱动程序由Playwright自动处理
重启服务器和Claude Desktop
- 终止可能正在运行服务器的所有现有Node进程
- 重新启动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内置浏览器通常不会遇到这个问题

[!CAUTION] 此MCP集成基于Playwright构建，而Playwright有一些已知的问题和漏洞可能会影响其操作。请将遇到的任何浏览器自动化问题报告给Playwright的GitHub问题。尽管存在这些限制，但该代理为Claude Desktop提供了浏览器自动化功能的基础，Playwright团队也在持续努力解决这些问题。

开发

项目结构- `src/index.ts`: 主入口点和MCP服务器初始化

src/tools.ts: 工具模式和注册
src/handlers.ts: 用于工具和资源的MCP请求处理器
src/executor.ts: 使用Playwright实现的工具逻辑

构建

npm run build

监视更改

npm run watch

测试

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

npm test # 运行测试 npm run test:watch # 监视模式 npm run test:coverage # 覆盖率报告

测试验证配置完整性、浏览器自动化特性、错误处理以及进程清理。测试套件特别关注确保对浏览器进程的正确处理，因为已知存在Chrome/Chromium终止的问题。

安全注意事项

[!IMPORTANT] 此MCP集成提供了Claude自主控制浏览器的能力。请查阅我们的安全政策，了解有关禁止使用、安全影响和最佳实践的重要信息。

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

贡献

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

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

许可证

本项目根据Mozilla Public License 2.0许可发布 - 详情请参阅LICENSE文件。

服务配置

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

来源

来源：github
链接：https://github.com/imprvhub/mcp-browser-agent

imprvhub