shield_lock
金大哥
← 返回 MCP 目录
public公开dns本地运行

mcp-browser-agent

MCP浏览器代理是一个强大的模型上下文协议集成，为Claude Desktop提供自主浏览器自动化能力，支持导航、截图、DOM交互、JavaScript执行和API请求等功能。

article

README

🚀 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
  1. 安装依赖项：
npm install
  1. 构建项目：
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建立通信。
  1. 工具注册表（tools.ts）
  • 定义浏览器和API工具模式。
  • 指定参数、验证规则和描述。
  • 向MCP服务器注册工具以供Claude发现。
  1. 请求处理程序（handlers.ts）
  • 管理工具和资源的MCP协议请求。
  • 将浏览器日志和屏幕截图作为可查询资源公开。
  • 将工具执行请求路由到适当的处理程序。
  1. 执行器（executor.ts）
  • 管理浏览器和API客户端的生命周期。
  • 使用Playwright实现浏览器自动化功能。
  • 处理API请求并进行适当的错误处理和响应解析。
  • 在命令之间维护有状态的浏览器会话。

代理功能

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

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

🐞 故障排除

"服务器断开连接"错误

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

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

浏览器未出现

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

  1. 检查指定的浏览器是否已安装：
  • 验证你已在系统上安装了浏览器（Chrome、Firefox、Edge或Safari/WebKit）。
  • 浏览器驱动程序由Playwright自动处理。
  1. 重启服务器和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>终止它。
  1. 关于浏览器兼容性的注意事项：
  • 此问题主要在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 文件。

🔗 相关链接

help

运行方式说明

cloud

托管运行

托管运行通常表示这个 MCP Server 由服务方环境承载，用户一般按页面提供的连接方式或授权流程接入，不需要在本地长期启动一个 MCP 进程

  1. 打开服务方连接页
  2. 完成授权或复制端点
  3. 在 MCP 客户端中连接
terminal

本地运行 / 其它方式

本地运行通常需要用户在自己的电脑或服务器上安装依赖，把 server_config 复制到 MCP 客户端，并按 env_schema 补齐环境变量、密钥或其它配置

  1. 复制 server_config
  2. 安装所需依赖
  3. 补齐环境变量后重启客户端