MCP Browser Agent

🚀 MCP浏览器代理

MCP浏览器代理是一款强大的Model Context Protocol（MCP）集成工具，它赋予Claude Desktop自主的浏览器自动化能力，可帮助用户更高效地完成各类网页操作和API请求。

🚀 快速开始

要使用MCP浏览器代理，你需要满足以下要求：

• 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是使用Chromium浏览器实例并带有'msedge'通道参数启动的，因为Microsoft Edge基于Chromium。

安装步骤

手动安装

1. 克隆或下载此仓库：

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

2. 安装依赖项：

npm install

3. 构建项目：

npm run build

运行MCP服务器

有两种方法可以运行MCP服务器：

方法一：手动运行

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

node dist/index.js

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

方法二：随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，但你可以通过以下几种方式指定不同的浏览器：

方式一：配置文件

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

{
  "browserType": "chrome"
}

browserType支持的值包括：

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

方式二：命令行参数

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

node dist/index.js --browser firefox

方式三：环境变量

设置MCP_BROWSER_TYPE环境变量：

MCP_BROWSER_TYPE=firefox node dist/index.js

方式四：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"
      ]
    }
  }
}

✨ 主要特性

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

💻 使用示例

基础用法

以下是一些使用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

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

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

📚 详细文档

可用工具

浏览器工具

工具名称	描述	参数
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浏览器代理基于Model Context Protocol构建，使Claude能够通过Playwright与有头浏览器进行交互。该实现包含四个主要组件：

1. 服务器（index.ts）

• 使用Model Context Protocol标准协议初始化MCP服务器。
• 配置服务器的工具和资源功能。
• 通过stdio传输与Claude建立通信。

2. 工具注册表（tools.ts）

• 定义浏览器和API工具模式。
• 指定参数、验证规则和描述。
• 向MCP服务器注册工具以供Claude发现。

3. 请求处理程序（handlers.ts）

• 管理工具和资源的MCP协议请求。
• 将浏览器日志和屏幕截图作为可查询资源公开。
• 将工具执行请求路由到适当的处理程序。

4. 执行器（executor.ts）

• 管理浏览器和API客户端的生命周期。
• 使用Playwright实现浏览器自动化功能。
• 处理API请求并进行适当的错误处理和响应解析。
• 在命令之间维护有状态的浏览器会话。

代理功能

与基本集成不同，MCP浏览器代理作为真正的AI代理，具有以下特点：

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

🐞 故障排除

"服务器断开连接"错误

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

1. 验证服务器是否正在运行：

• 打开终端，从项目目录手动运行node dist/index.js。
• 如果服务器成功启动，请在保持此终端打开的情况下使用Claude。

2. 检查你的配置：

• 确保claude_desktop_config.json中的绝对路径对于你的系统是正确的。
• 仔细检查Windows路径是否使用了双反斜杠 (\\)。
• 验证你使用的是从文件系统根目录开始的完整路径。

浏览器未出现

如果浏览器未启动或你看不到它：

1. 检查指定的浏览器是否已安装：

• 验证你已在系统上安装了浏览器（Chrome、Firefox、Edge或Safari/WebKit）。
• 浏览器驱动程序由Playwright自动处理。

2. 重启服务器和Claude Desktop：

• 终止任何可能正在运行服务器的现有节点进程。
• 重启Claude Desktop以建立新连接。

浏览器进程未正确关闭

Chromium和Chrome浏览器存在已知问题，有时使用后进程不会正确终止。如果你遇到此问题：

1. 手动关闭浏览器进程：

• Windows：按Ctrl+Shift+Esc打开任务管理器，找到Chrome/Chromium进程并结束它。
• macOS：打开活动监视器（应用程序 > 实用工具 > 活动监视器），找到Chrome/Chromium进程并点击X终止它。
• Linux：运行ps aux | grep chrome或ps aux | grep chromium查找进程，然后使用kill <PID>终止它。

2. 关于浏览器兼容性的注意事项：

• 此问题主要在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               # 运行测试
npm run test:watch     # 监视模式
npm run test:coverage  # 覆盖率报告

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

⚠️ 安全考虑

⚠️ 重要提示

此MCP集成赋予Claude自主的浏览器控制能力。请查看我们的 安全策略，了解有关禁止使用、安全影响和最佳实践的重要信息。

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

👥 贡献

欢迎为MCP浏览器代理做出贡献！你可以在以下方面提供帮助：

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

📄 许可证

本项目采用Mozilla公共许可证2.0 - 有关详细信息，请参阅 LICENSE 文件。

🔗 相关链接

• Model Context Protocol
• Claude Desktop
• Playwright文档
• MCP系列