Puppeteer Real Browser MCP Server

🚀 Puppeteer Real Browser MCP Server

Puppeteer Real Browser MCP Server 是一个模型上下文协议（MCP）服务器，借助 puppeteer-real-browser 为 AI 助手提供强大且不易被检测的浏览器自动化功能。

🚀 快速开始

项目介绍

这是一个 MCP（模型上下文协议）服务器，它能让像 Claude 这样的 AI 助手控制真实的网络浏览器。可以把它想象成给 Claude 装上了“手”，使其能够点击按钮、填写表单、截图等，同时还能避免被机器人检测机制识别。

逐步设置

1. 安装 Node.js

• 访问 nodejs.org
• 下载并安装 Node.js（版本 18 或更高）
• 打开终端或命令提示符，输入 node --version 验证安装情况

2. 与 Claude Desktop 集成（无需安装）

使用 npx 命令将自动下载并运行最新版本，无需手动安装。

3. 配置 Claude Desktop

Windows 系统：

1. 打开文件资源管理器，导航到 %APPDATA%\Claude\
2. 打开（或创建）claude_desktop_config.json 文件
3. 添加以下配置：

{
  "mcpServers": {
    "puppeteer-real-browser": {
      "command": "npx",
      "args": ["puppeteer-real-browser-mcp-server@latest"]
    }
  }
}

Mac 系统：

1. 打开 Finder，按下 Cmd + Shift + G
2. 进入 ~/Library/Application Support/Claude/
3. 打开（或创建）claude_desktop_config.json 文件
4. 添加与上述相同的配置

Linux 系统：

1. 导航到 ~/.config/Claude/
2. 打开（或创建）claude_desktop_config.json 文件
3. 添加与上述相同的配置

4. 重启 Claude Desktop

完全关闭并重新打开 Claude Desktop。

5. 测试功能

在 Claude Desktop 中，尝试输入：

"初始化浏览器并导航到 google.com，然后截取屏幕截图"

如果一切正常，Claude 应该能够：

• 启动浏览器
• 导航到 Google 页面
• 截取屏幕截图并展示给你

功能使用

配置完成后，你可以要求 Claude 执行以下操作：

• 浏览网站：“访问 amazon.com 并搜索笔记本电脑”
• 填写表单：“用我的详细信息填写此联系表单”
• 截取屏幕截图：“展示此页面的外观”
• 提取数据：“从此页面获取所有产品价格”
• 自动化任务：“登录我的账户并下载我的发票”
• 解决验证码：“处理出现的任何验证码”

安全提示

• Claude 会展示其操作过程，你可以看到浏览器窗口
• 在批准敏感操作之前，请始终审查 Claude 的操作
• 如果你不想看到浏览器窗口，可以使用无头模式（headless: true）
• 请遵守网站的使用条款

✨ 主要特性

• 默认隐身模式：所有浏览器实例均使用反检测功能
• 增强页面方法：支持 page.realClick 和 page.realCursor
• 高级配置：全面支持所有 puppeteer-real-browser 选项
• 类人操作：具备自然交互工具，避免被检测
• 综合工具集：拥有 16 种以上工具，满足所有浏览器自动化需求
• 代理支持：内置代理配置，增强隐私保护
• 验证码处理：支持解决 reCAPTCHA、hCaptcha 和 Turnstile 验证码
• 目标管理：支持 setTarget 函数
• 错误处理：强大的错误处理和报告机制

📦 安装指南

通过 npm 安装

npm install -g puppeteer-real-browser-mcp-server

从源代码安装

# 克隆仓库
git clone https://github.com/withLinda/puppeteer-real-browser-mcp-server.git
cd puppeteer-real-browser-mcp-server

# 安装依赖
npm install

# 构建项目
npm run build

💻 使用示例

与 Claude Desktop 集成

在 Claude Desktop 配置文件中添加以下内容：

{
  "mcpServers": {
    "puppeteer-real-browser": {
      "command": "npx",
      "args": ["puppeteer-real-browser-mcp-server@latest"]
    }
  }
}

与其他 AI 助手集成

启动服务器：

puppeteer-real-browser-mcp-server

如果你是从源代码安装的，可以使用以下命令启动：

npm start

服务器通过标准输入/输出使用 MCP 协议进行通信。

交互示例

基础网页浏览

用户："初始化浏览器并导航到 example.com"
AI：我将初始化一个隐身浏览器并导航到该网站。
[使用 browser_init 和 navigate 工具]

用户："截取主内容区域的屏幕截图"
AI：我将截取页面的屏幕截图。
[使用 screenshot 工具]

表单自动化

用户："在搜索表单中输入 'test query'"
AI：我将以类人打字方式在搜索字段中输入该内容。
[使用 human_like_type 工具，指定选择器和文本]

用户："点击搜索按钮"
AI：我将以类人移动方式点击搜索按钮。
[使用 human_like_click 工具]

数据提取

用户："从此电子商务页面获取所有产品名称"
AI：我将从页面中提取产品信息。
[使用 get_content 工具，指定合适的选择器]

用户："将页面内容保存为文本"
AI：我将获取整个页面的文本内容。
[使用 get_content 工具，指定类型为 'text']

高级交互

用户："在下拉菜单上使用真实点击"
AI：我将使用增强的 real_click 方法进行更好的交互。
[使用 real_click 工具，指定选择器和选项]

用户："将光标平滑移动到坐标 500, 300 处"
AI：我将使用增强的移动方式移动光标。
[使用 real_cursor 工具，指定 x、y 坐标和步长选项]

使用代理

用户："使用代理服务器初始化浏览器"
AI：我将使用你的代理配置设置浏览器。
[使用 browser_init 工具，指定代理为 "https://proxy.example.com:8080"]

📚 详细文档

可用工具

核心浏览器工具

工具名称	描述	必需参数	可选参数
browser_init	使用高级选项初始化隐身浏览器	无	headless、disableXvfb、ignoreAllFlags、proxy、plugins、connectOption
navigate	导航到指定 URL	url	waitUntil
screenshot	截取页面或元素的屏幕截图	无	fullPage、selector
get_content	获取页面内容（HTML 或文本）	无	type、selector
browser_close	关闭浏览器实例	无	无

交互工具

工具名称	描述	必需参数	可选参数
click	对元素执行标准点击操作	selector	waitForNavigation
type	在输入字段中输入文本	selector、text	delay
wait	等待各种条件满足	type、value	timeout

增强的 Puppeteer-Real-Browser 工具

工具名称	描述	必需参数	可选参数
real_click	使用 page.realClick 进行增强点击操作	selector	options（按钮、点击次数、延迟）
real_cursor	使用 page.realCursor 进行增强光标移动	selector 或 x、y	options（步数）
set_target	使用 setTarget 函数进行高级目标定位	target	无

类人行为工具

工具名称	描述	必需参数	可选参数
human_like_click	以类人鼠标移动方式点击	selector	无
human_like_type	以类人输入时间间隔输入文本	selector、text	无
random_scroll	以自然时间间隔执行随机滚动	无	无

反检测工具

工具名称	描述	必需参数	可选参数
solve_captcha	尝试解决验证码	type	无

高级功能

类人交互

服务器包含多个模拟人类行为的工具：

• 类人鼠标移动：以自然、非线性路径移动光标
• 可变输入速度：按键之间随机延迟输入
• 随机滚动：以自然时间间隔和可变距离执行滚动

这些功能有助于避免被分析用户行为模式的复杂机器人检测系统识别。

验证码处理

服务器基本支持解决常见类型的验证码：

• reCAPTCHA
• hCaptcha
• Cloudflare Turnstile

请注意，验证码解决能力取决于底层 puppeteer-real-browser 的实现。

配置说明

配置自定义选项（如无头模式）

自定义选项（如无头模式）不在 MCP 配置文件中配置。相反，它们在使用 browser_init 工具初始化浏览器时传递。

当你要求 Claude 初始化浏览器时，你可以指定以下选项：

请初始化一个启用无头模式并设置 30 秒超时的浏览器

Claude 将使用 browser_init 工具并传递相应参数：

{
  "headless": true,
  "connectOption": {
    "timeout": 30000
  }
}

可用浏览器选项

使用 browser_init 初始化时，你可以配置以下选项：

• headless：true/false（设置为 true 以启用无头模式）
• disableXvfb：true/false（禁用 X 虚拟帧缓冲）
• ignoreAllFlags：true/false（忽略所有 Chrome 标志）
• proxy："https://proxy:8080"（代理服务器 URL）
• plugins：["plugin1", "plugin2"]（要加载的插件数组）
• connectOption：其他连接选项，如：
  • slowMo：250（以毫秒为单位减慢操作速度）
  • timeout：60,000（连接超时时间）

MCP 配置文件仅告知 Claude 服务器的位置，所有特定于浏览器的选项都通过与 Claude 的对话进行配置。

浏览器选项示例

使用 browser_init 初始化浏览器时，你可以进行如下配置：

{
  "headless": false,
  "disableXvfb": false,
  "ignoreAllFlags": false,
  "proxy": "https://proxy:8080",
  "plugins": ["plugin1", "plugin2"],
  "connectOption": {
    "slowMo": 250,
    "timeout": 60000
  }
}

高级配置示例

使用代理

{
  "headless": true,
  "proxy": "https://username:password@proxy.example.com:8080"
}

自定义选项隐身模式

{
  "headless": false,
  "ignoreAllFlags": true,
  "disableXvfb": false,
  "connectOption": {
    "slowMo": 100,
    "devtools": false
  }
}

增强真实浏览器功能

使用带有选项的 real_click：

{
  "selector": "#submit-button",
  "options": {
    "button": "left",
    "clickCount": 2,
    "delay": 150
  }
}

使用带有坐标的 real_cursor：

{
  "x": 500,
  "y": 300,
  "options": {
    "steps": 30
  }
}

服务器配置

对于高级用户，你可以通过编辑源代码来修改服务器行为：

• 在 initializeBrowser 函数中更改默认视口大小
• 调整各种操作的超时值
• 启用调试日志

🔧 技术细节

项目结构

puppeteer-real-browser-mcp-server/
├── src/
│   ├── index.ts         # 主服务器实现
│   └── stealth-actions.ts # 类人交互函数
├── test/
│   └── test-server.ts   # 测试脚本
├── package.json
└── tsconfig.json

从源代码构建

# 安装依赖
npm install

# 在开发模式下运行
npm run dev

# 构建生产版本
npm run build

# 测试服务器
npm test

添加新工具

要添加新工具，请按以下步骤操作：

1. 在 src/index.ts 的 TOOLS 数组中添加工具定义
2. 在 CallToolRequestSchema 处理程序中实现工具处理逻辑
3. 测试新工具的功能

📄 许可证

本项目采用 MIT 许可证，请参阅 LICENSE 文件以获取详细信息。

常见问题解答与故障排除

常见问题

1. 使用 npx 时出现 "command not found" 或 "syntax error"

   • 此问题在 1.0.3 版本中已通过添加适当的 shebang 行修复
   • 确保使用的是最新版本：npx puppeteer-real-browser-mcp-server@latest
   • 全局安装：npm install -g puppeteer-real-browser-mcp-server@latest
   • 如果仍然存在问题，请全局安装：npm install -g puppeteer-real-browser-mcp-server
   • 检查你的 PATH 环境变量是否包含 npm 全局二进制文件路径：npm config get prefix

2. 浏览器无法启动

   • 检查是否安装了 Chrome 或 Chromium 浏览器
   • Linux 系统：安装依赖：sudo apt-get install -y chromium-browser
   • Windows 系统：确保已安装 Chrome 浏览器
   • 首先尝试使用 headless: true 模式

3. Claude 无法识别 MCP 服务器

   • 验证 claude_desktop_config.json 文件是否位于正确的位置
   • 检查 JSON 语法是否有效（可使用 jsonlint.com 进行验证）
   • 完全重启 Claude Desktop
   • 检查 Claude Desktop 中的任何错误消息

4. 权限被拒绝错误

   • Linux/Mac 系统：尝试使用 sudo npm install -g puppeteer-real-browser-mcp-server
   • 或者使用 nvm 管理 Node.js，避免使用 sudo
   • Windows 系统：以管理员身份运行命令提示符

5. 检测问题

   • 使用 real_click 和 real_cursor 代替基本点击操作
   • 启用类人工具：human_like_click、human_like_type
   • 使用 random_scroll 添加随机延迟
   • 如有需要，使用代理：proxy: "http://proxy.example.com:8080"

6. 内存泄漏问题

   • 完成操作后，始终使用 browser_close 关闭浏览器实例
   • 不要在未关闭之前的浏览器实例的情况下初始化多个浏览器
   • 检查是否存在未捕获的异常，可能会阻止清理操作

7. 超时错误

   • 增加超时值：{ "timeout": 60000 }
   • 在与元素交互之前使用 wait 工具
   • 检查网络连接和网站响应时间

常见问答

问：该项目是否支持无头浏览器？ 答：是的，在 browser_init 选项中设置 headless: true 即可。

问：我可以同时使用多个浏览器吗？ 答：目前仅支持一个浏览器实例。在启动新的浏览器实例之前，请关闭当前的实例。

问：它可以解决哪些类型的验证码？ 答：通过 puppeteer-real-browser 支持解决 reCAPTCHA、hCaptcha 和 Cloudflare Turnstile 验证码。

问：该项目会被网站检测到吗？ 答：puppeteer-real-browser 包含反检测功能，但没有任何解决方案是 100% 不可检测的。

问：我可以使用自定义 Chrome 扩展吗？ 答：是的，通过 browser_init 中的 plugins 选项可以实现。

问：该项目是否支持所有操作系统？ 答：是的，已经在 Windows、macOS 和 Linux 系统上进行了测试。

调试模式

要启用调试日志，请使用以下命令：

DEBUG=true npm start

或者从源代码运行时：

DEBUG=true npm run dev

获取帮助

如果你仍然遇到问题，请按照以下步骤操作：

1. 查看 GitHub Issues
2. 创建一个新的问题，并提供以下信息：
   • 你的操作系统
   • Node.js 版本（node --version）
   • npm 版本（npm --version）
   • 完整的错误消息
   • 重现问题的步骤

贡献代码

欢迎贡献代码！请随时提交拉取请求。

1. 分叉仓库
2. 创建你的功能分支（git checkout -b feature/amazing-feature）
3. 提交更改（git commit -m 'Add some amazing feature'）
4. 推送到分支（git push origin feature/amazing-feature）
5. 打开拉取请求