MCP浏览器代理
 ](https://smithery.ai/server/@imprvhub/mcp-browser-agent)
A powerful Model Context Protocol (MCP) integration that provides Claude Desktop with autonomous browser automation capabilities.
特性
- 高级浏览器自动化
- 使用可定制的加载策略导航到任何URL - 捕获整页或特定元素的屏幕截图 - 执行精确的DOM交互（单击、填充、选择、悬停） - 在浏览器上下文中执行任意JavaScript，并捕获控制台日志
- 强大的API客户端
- 执行HTTP请求（GET、POST、PUT、PATCH、DELETE） - 配置请求头和正文内容 - 处理JSON格式的响应数据 - 错误处理和详细反馈
- MCP资源管理
- 将浏览器控制台日志作为资源访问 - 通过MCP资源界面检索屏幕截图 - 与令人头疼的浏览器实例进行持续会话
- AI代理功能
- 为复杂任务链接多个浏览器操作 - 遵循智能错误恢复的多步骤说明 - 通过自然语言指令实现技术任务自动化
演示
Timestamps:
点击任何时间戳跳转到视频的该部分
00:00 - 谷歌搜索MCP\ 导航到谷歌主页并搜索“模型上下文协议”。演示Claude Desktop使用MCP集成执行基本的网络搜索并处理结果。
00:33 - 电脑屏幕截图工具\ 使用自定义文件名对搜索结果进行截图，并在Finder中展示。演示Claude如何在浏览器自动化过程中捕获和保存网页中的视觉内容。
01:00 - 维基百科搜索\ 导航到Wikipedia.org并搜索“模型上下文协议”。展示了Claude通过MCP集成与不同网站及其搜索功能进行交互的能力。
01:38 - 下拉菜单交互I\ 导航到测试网站（internet.herokuapp.com/dropdown），从下拉菜单中选择“选项1”。展示Claude与表单元素交互和进行选择的能力。
01:56 - 下拉菜单交互II\ 从同一下拉菜单中将选择更改为“选项2”。展示了Claude多次操纵同一表单元素并做出不同选择的能力。
02:09 - 登录表单完成\ 导航到登录页面（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（默认）
- 火狐
- 微软边缘
- 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自动启动（建议常规使用）
克劳德桌面可以在需要时自动启动MCP服务器。要设置此项，请执行以下操作：
配置
Claude Desktop配置文件位于：
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - 视窗:
%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中配置MCP时 claude_desktop_config.json，您可以指定浏览器类型：
{
"mcpServers": {
"browserAgent": {
"command": "node",
"args": [
"ABSOLUTE_PATH_TO_DIRECTORY/mcp-browser-agent/dist/index.js",
"--browser",
"chrome"
]
}
}
}技术实现
MCP浏览器代理基于模型上下文协议构建，使Claude能够通过Playwright与令人头疼的浏览器进行交互。实施由四个主要部分组成：
- 服务器（index.ts）
- 使用模型上下文协议标准协议初始化MCP服务器 - 为工具和资源配置服务器功能 - 通过stdio传输与Claude建立通信
- 工具注册表（Tools.ts）
- 定义浏览器和API工具架构 - 指定参数、验证规则和说明 - 向MCP服务器注册工具以供Claude发现
- 请求处理程序（handler.ts）
- 管理MCP协议对工具和资源的请求 - 将浏览器日志和屏幕截图作为可查询资源公开 - 将工具执行请求路由到适当的处理程序
- 执行人（executive.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]-按名称访问屏幕截图
示例用法
以下是一些如何与Claude一起使用MCP浏览器代理的实际示例：
基本浏览器导航
Navigate to the Google homepage at https://www.google.comTake 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 titleNavigate to https://www.google.com and execute a JavaScript script to count the number of links on the pageAPI基本请求
Perform a GET request to https://jsonplaceholder.typicode.com/todos/1Make 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浏览器存在已知问题，使用后进程有时无法正确终止。如果您遇到此问题：
- 手动关闭浏览器进程:
- 视窗：按Ctrl+Shift+Esc打开任务管理器，找到Chrome/Chromium进程并结束它 - macOS：打开活动监视器（应用程序>实用程序>活动监视器），找到Chrome/Chromium进程，然后单击X终止它 - Linux：运行 ps aux | grep chrome 或 ps aux | grep chromium 找到过程，然后 kill 终止它
- 关于浏览器兼容性的注意事项:
- 此问题主要在Chromium和Chrome中观察到 - Firefox和Playwright的内置浏览器通常不会遇到这个问题
\[！小心\] 此MCP集成建立在Playwright之上，Playwright存在可能影响其运行的已知问题和错误。请将您在浏览器自动化方面遇到的任何问题报告给 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获得许可-请参阅 许可证 文件以获取详细信息。