Puppeteer真实浏览器MCP服务器

Name: Puppeteer真实浏览器MCP服务器
Author: withLinda

作者：withLinda13 星标更新：2025-08-26

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

项目介绍

【技术文档摘要】

⚠️ 维护中 - 此项目仍在积极开发中。某些功能可能不完整或未经通知更改。

Puppeteer 实时浏览器 MCP 服务器

提供强大的、能够抵抗检测的浏览器自动化能力，基于 ZFC 数字公司的 puppeteer-real-browser 包，供 AI 助手使用。

初学者快速入门

这是什么？

这是一个 MCP（模型上下文协议）服务器，让像 Claude 这样的 AI 助手控制一个真实的网络浏览器。可以将其视为给 Claude “手”，使其能够与网站互动——它可以点击按钮、填写表单、提取内容等等，同时避免被机器人检测到。

重要提示：您不需要安装此包！

如果您只是使用这个 MCP 服务器（而不是开发它），您不需要运行 npm install。配置中的 npx 命令会自动下载并运行最新版本。安装仅在开发目的时需要。

分步设置

1. 安装 Node.js（必需）

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

2. 配置 Claude Desktop

对于 Windows：

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

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

对于 Mac：

打开 Finder 并按 Cmd+Shift+G
转到：~/Library/Application Support/Claude/
打开（或创建）claude_desktop_config.json
添加相同的配置

对于 Linux：

导航到：~/.config/Claude/
打开（或创建）claude_desktop_config.json
添加相同的配置

为什么使用 @latest？ @latest 标签确保您始终获得最新的版本，包括错误修复和改进。npx 命令会自动下载并运行它，而无需永久安装在您的系统上。

3. 重新启动 Claude Desktop

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

4. 测试是否正常工作

在 Claude Desktop 中，尝试说：

"初始化浏览器并导航到 google.com，然后获取页面内容"

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

启动浏览器
导航到 Google
提取并显示页面内容

您能用它做什么？

一旦设置好，您可以要求 Claude：

浏览网站："去亚马逊.com 并搜索笔记本电脑"
填写表单："用我的详细信息填写这个联系表单"
提取数据："从这一页获取所有产品价格"
自动化任务："登录我的账户并下载发票"
解决验证码："处理出现的任何验证码"

安全注意事项

Claude 会显示它正在做的事情——您可以看到浏览器窗口
在批准敏感操作之前，请务必审查 Claude 的行为
使用无头模式（headless: true）如果您不想看到浏览器窗口
尊重网站的服务条款

简介

Puppeteer 实时浏览器 MCP 服务器充当 AI 助手和浏览器自动化之间的桥梁。它利用 puppeteer-real-browser 提供能够绕过常见机器人检测机制的隐身浏览功能。

此服务器实现了模型上下文协议（MCP），允许 AI 助手控制真实浏览器、提取内容等。

特性

默认隐身：所有浏览器实例都使用反检测功能
增强的 Windows 支持：全面的 Chrome 检测和 ECONNREFUSED 错误修复（v1.3.0）
智能 Chrome 检测：基于注册表的检测 + 15+ 安装路径（Windows）
连接韧性：自动本地主机/127.0.0.1 回退及端口管理
多种重试策略：5 种不同的连接方式及逐步回退
高级配置：全面支持所有 puppeteer-real-browser 选项
动态选择器发现：智能元素查找，无需硬编码选择器
随机滚动：用于自然滚动以避免检测的工具
综合工具集：11 种工具覆盖所有浏览器自动化需求
代理支持：内置代理配置以增强隐私
验证码处理：支持解决 reCAPTCHA、hCaptcha 和 Turnstile
强大的错误处理：先进的错误恢复机制，采用断路器模式
堆栈溢出保护：全面防止无限递归
超时控制：自动超时机制防止挂起的操作
平台优化：Windows 特定标志和更长的超时时间以提高兼容性

前提条件

Node.js >= 18.0.0
npm 或 yarn
已安装的 Google Chrome 或 Chromium 浏览器
对 TypeScript/JavaScript 的基本理解（用于开发）

平台特定要求

Windows：

Google Chrome 安装（自动检测 v1.3.0+ 包括）：
- 标准安装：C:\Program Files\Google\Chrome\Application\chrome.exe
- 32 位安装：C:\Program Files (x86)\Google\Chrome\Application\chrome.exe
- 用户安装：%LOCALAPPDATA%\Google\Chrome\Application\chrome.exe
- Chrome Canary：%LOCALAPPDATA%\Google\Chrome SxS\Application\chrome.exe
- 可携带安装和注册表检测路径
- 手动路径指定：使用 CHROME_PATH 环境变量

macOS：

Google Chrome 或 Chromium 必须安装在 /Applications/

Linux：

安装 Chrome/Chromium：sudo apt-get install -y google-chrome-stable 或 sudo apt-get install -y chromium-browser
安装 xvfb 用于无头操作：sudo apt-get install -y xvfb

开发者安装

注意：Claude Desktop 用户无需安装任何东西！配置中的 npx 命令会自动处理一切。跳转至使用方法部分。

本节适用于希望：

贡献于该项目
在本地运行服务器进行开发
创建自定义修改

全局安装（用于命令行使用）

如果您想直接从命令行运行服务器而不使用 npx：

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

全局安装后，您可以运行：

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

# 开发模式运行
npm run dev

使用方法

与 Claude Desktop 一起使用

以下配置使用 npx 自动下载并运行最新版本。无需安装！

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

npx 做了什么？ npx 命令下载并运行包，而不会永久安装它。@latest 确保您始终获得带有所有错误修复和改进的新版本。

与 Claude Code CLI 一起使用

Claude Code CLI 提供多种便捷方法添加 puppeteer-real-browser MCP 服务器。选择最适合您工作流程的方法：

方法 1：快速设置（推荐）

最快开始的方式是使用 claude mcp add 命令：

claude mcp add puppeteer-real-browser -- npx puppeteer-real-browser-mcp-server@latest

此命令：

将服务器添加到本地作用域（仅当前项目可用）
使用 npx 自动下载并运行最新版本
不需要安装——一切都自动处理

方法 2：使用环境变量添加

如果您需要配置代理设置或自定义 Chrome 路径：

claude mcp add puppeteer-real-browser \
  -e CHROME_PATH="/path/to/chrome" \
  -e PROXY_URL="http://proxy:8080" \
  -- npx puppeteer-real-browser-mcp-server@latest

方法 3：作用域配置

对于跨所有项目的用户范围（可用）：

claude mcp add puppeteer-real-browser -s user -- npx puppeteer-real-browser-mcp-server@latest

对于整个项目的范围（通过 .mcp.json 与团队共享）：

claude mcp add puppeteer-real-browser -s project -- npx puppeteer-real-browser-mcp-server@latest

方法 4：JSON 配置

对于需要精确控制的高级用户：

claude mcp add-json puppeteer-real-browser '{
  "type": "stdio",
  "command": "npx",
  "args": ["puppeteer-real-browser-mcp-server@latest"],
  "env": {
    "CHROME_PATH": "/path/to/chrome",
    "PROXY_URL": "http://proxy:8080"
  }
}'

验证和测试

添加服务器后：

检查 MCP 服务器状态：
```
/mcp
```
在 Claude Code 中使用此命令查看所有活动的 MCP 服务器。
测试服务器： 在 Claude Code 中尝试：

"初始化浏览器并导航到 google.com，然后获取页面内容"

如果正确工作，您应该看到：
- 浏览器初始化
- 导航到 Google
- 页面内容提取并显示

配置范围解释

范围	描述	配置位置	使用场景
local（默认）	仅在当前项目中对您可用	项目中的 `.mcp.json`	测试、项目特定
project	整个团队共享	提交到仓库的 `.mcp.json`	团队协作
user	跨所有项目对您可用	用户配置目录	个人生产力

Claude Code CLI 的优点

自动更新：使用 @latest 确保您获得错误修复和改进
无需安装：npx 自动处理下载和运行
环境变量：轻松配置代理、Chrome 路径等
作用域控制：选择服务器可用的位置（local/project/user）
团队共享：项目范围允许与队友共享配置
状态监控：内置 /mcp 命令用于服务器健康检查

与 Cursor IDE 一起使用

Cursor IDE 也使用相同的 npx 方法——无需安装！以下是设置方法：

方法 1：一键安装（推荐）

打开 Cursor IDE
打开命令面板（Windows/Linux 上为 Ctrl+Shift+P，Mac 上为 Cmd+Shift+P）
**搜索“Cursor 设置”**并选择它
点击侧边栏中的“MCP”
浏览精选的 MCP 服务器，并通过单击安装浏览器自动化工具
OAuth 认证将自动处理

方法 2：手动配置

配置文件位置：

项目特定：在项目目录中创建 .cursor/mcp.json
全局：在您的主目录中创建 ~/.cursor/mcp.json

基本配置（无需安装）：

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

重要：就像 Claude Desktop 一样，Cursor 将使用 npx 自动下载并运行服务器。您不需要使用 npm 安装任何东西！

Windows 特定配置（如果遇到 Chrome 路径问题）：

{
  "mcpServers": {
    "puppeteer-real-browser": {
      "command": "npx",
      "args": ["puppeteer-real-browser-mcp-server@latest"],
      "env": {
        "CHROME_PATH": "C:/Program Files/Google/Chrome/Application/chrome.exe"
      }
    }
  }
}

注意：浏览器选项如无头模式应在通过 browser_init 工具初始化浏览器时配置，而不是通过环境变量。

具有自定义 Chrome 路径的高级配置：

{
  "mcpServers": {
    "puppeteer-real-browser": {
      "command": "npx",
      "args": ["puppeteer-real-browser-mcp-server@latest"],
      "env": {
        "CHROME_PATH": "C:/Program Files/Google/Chrome/Application/chrome.exe"
      }
    }
  }
}

注意：代理设置和浏览器选项应在请求 Claude 初始化浏览器时通过 browser_init 工具配置。

Cursor IDE 的平台特定 Chrome 路径

如果 Chrome 自动检测失败，您可以使用 CHROME_PATH 环境变量指定 Chrome 路径：