浏览器代理

Name: 浏览器代理
Author: imprvhub

作者：imprvhub28 星标更新：2025-10-22

安装使用来源：spider==github.com

项目介绍

MCP Browser Agent

<table style="border-collapse: collapse; width: 100%; table-layout: fixed;"> <tr> <td style="width: 40%; padding: 15px; vertical-align: middle; border: none;">一个强大的模型上下文协议（MCP）集成，为Claude Desktop提供自主浏览器自动化功能。</td> <td style="width: 60%; padding: 0; vertical-align: middle; border: none; min-width: 300px; text-align: center;"><a href="https://glama.ai/mcp/servers/@imprvhub/mcp-browser-agent"> <img style="max-width: 100%; height: auto; min-width: 300px;" src="https://gips0.baidu.com/it/u=2795878889,3600665382&fm=3081&app=3081&f=PNG?w=760&h=400" alt="Browser Agent MCP server" /> </a></td> </tr> </table>

功能

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

示例

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

00:00 - 在MCP中搜索Google
导航到Google首页并搜索“模型上下文协议”。演示Claude Desktop如何使用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通过MCP集成直接调用API并处理返回数据的能力。

</details>

要求

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

浏览器支持

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 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

编辑此文件以添加Browser Agent 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 Browser Agent支持多种浏览器类型。默认情况下，它使用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 Desktop配置

在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 Browser Agent基于模型上下文协议构建，使Claude能够通过Playwright与头部浏览器互动。实现由四个主要组件组成：

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

代理能力

与基本集成不同，MCP Browser Agent作为一个真正的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 Agent公开以下资源：

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

示例用法

这里有一些实际的例子，说明如何使用MCP Browser Agent与Claude：

基本浏览器导航

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

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

在搜索框中键入“天气预报”

简单互动

导航到 https://www.wikipedia.org 并搜索“模型上下文协议”

前往 https://the-internet.herokuapp.com/dropdown 并从下拉菜单中选择“选项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 发送POST请求，并附带适当的JSON数据

这些例子代表了MCP Browser Agent的实际能力，并且更现实地反映了它目前的状态。

故障排除

“服务器断开连接”错误

如果你在Claude Desktop中看到“MCP Browser Agent: 服务器断开连接”的错误：

验证服务器是否正在运行：
- 打开终端并手动运行 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存在已知的问题和bug，可能会影响其操作。请将你在浏览器自动化方面遇到的任何问题报告给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               # 运行测试
npm run test:watch     # 监视模式
npm run test:coverage  # 覆盖报告

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

安全考虑

[!IMPORTANT] 此