⚠️ 维护中 -该项目仍在积极开发中。某些功能可能不完整或更改，恕不另行通知。

Puppeter真实浏览器MCP服务器

为AI助手提供强大的、抗检测的浏览器自动化功能，该功能基于ZFC Digital的木偶师真实浏览器包构建。

![License: MIT](https://opensource.org/licenses/MIT)

初学者快速入门

这是什么？

这是一个MCP（模型上下文协议）服务器，让像克劳德这样的人工智能助手控制一个真正的网络浏览器。把它想象成给克劳德“手”与网站互动——它可以点击按钮、填写表单、提取内容等等，同时避免机器人检测。

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

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

逐步设置

1.安装Node.js（必填）

首选
下载并安装Node.js（版本18或更高）
通过打开终端/命令提示符并键入以下内容来验证安装： node --version

2.配置克劳德桌面

对于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。

4.测试它是否有效

在Claude Desktop中，尝试说：

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

如果一切正常，克劳德应该能够：

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

你能用它做什么？

设置后，您可以要求Claude：

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

安全须知

Claude将向您展示它正在做什么-您可以看到浏览器窗口
在批准敏感行动之前，始终审查克劳德的工作
使用无头模式(headless: true)如果你不想看到浏览器窗口
尊重网站的服务条款

介绍

Puppeter Real Browser MCP服务器充当AI助手之间的桥梁以及浏览器自动化。它利用木偶师真实浏览器提供隐身功能浏览功能可以绕过常见的机器人检测机制。

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

特性

默认情况下隐藏：所有浏览器实例都使用反检测功能
增强的Windows支持：全面的Chrome检测和ECONNREFUSED错误修复（v1.3.0）
智能Chrome检测：基于注册表的检测+15+安装路径（Windows）
连接弹性：带端口管理的自动本地主机/127.0.0.1回退
多种重试策略：5种不同的连接方法，具有渐进式回退功能
高级配置：完全支持所有木偶师真实浏览器选项
动态选择器发现：无需硬编码选择器的智能元素查找
随机滚动：用于自然滚动以避免检测的工具
全面的工具集：11个工具，涵盖所有浏览器自动化需求
代理支持：内置代理配置，增强隐私
验证码处理：支持解决reCAPTCHA、hCaptcha和旋转栅门问题
稳健的错误处理：使用断路器模式进行高级错误恢复
堆栈溢出保护：全面防止无限递归
超时控制：自动超时机制防止挂起操作
平台优化：Windows特定的标志和更长的超时时间，以实现更好的兼容性

先决条件

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

平台特定要求

窗户：

安装谷歌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 - 铬金丝雀： %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桌面用户注意事项： 你不需要安装任何东西！配置中的npx命令会自动处理所有内容。跳到用法部分。

本节面向希望：

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

全局安装（用于命令行）

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

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

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

puppeteer-real-browser-mcp-server

开发设置（供贡献者使用）

# Clone the repository
git clone https://github.com/withLinda/puppeteer-real-browser-mcp-server.git
cd puppeteer-real-browser-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode
npm run dev

用法

使用克劳德桌面

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

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

npx是做什么的？ 这 npx 命令下载并运行包，而无需永久安装 @latest 确保您始终获得包含所有错误修复和改进的最新版本。

使用Claude Code CLI

Claude Code CLI提供了多种方便的方法来添加木偶师真实浏览器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，然后获取页面内容

如果工作正常，您应该看到：

- 浏览器初始化 - 导航到谷歌 - 提取并显示页面内容

配置范围说明

范围	描述	配置位置	用例
本地（默认）	仅在当前项目中对您可用	`.mcp.json` 在项目中	测试，项目特定
项目	与整个团队共享	`.mcp.json` 致力于回购	团队协作
用户	您可以在所有项目中使用	用户配置目录	个人生产力

Claude Code CLI的优点

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

使用游标IDE

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

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

打开光标IDE
打开命令选项板 (Ctrl+Shift+P 在Windows/Linux操作系统上， Cmd+Shift+P 在Mac上）
搜索“光标设置” 并选择它
点击侧栏中的“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 环境变量：

窗户：

"env": {
  "CHROME_PATH": "C:/Program Files/Google/Chrome/Application/chrome.exe"
}

替代Windows路径：

"C:/Program Files (x86)/Google/Chrome/Application/chrome.exe"
"%LOCALAPPDATA%/Google/Chrome/Application/chrome.exe"

macOS：

"env": {
  "CHROME_PATH": "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
}

Linux：

"env": {
  "CHROME_PATH": "/usr/bin/google-chrome"
}

替代Linux路径： /usr/bin/chromium-browser, /snap/bin/chromium

测试游标IDE设置

配置后：

完全重新启动Cursor IDE
打开新聊天
测试用：“初始化浏览器并导航到google.com，然后获取页面内容”

如果成功，您应该看到：

浏览器窗口打开
导航到谷歌
聊天中提取并显示的页面内容

游标IDE故障排除

常见问题：

“找不到MCP服务器”

- 验证配置文件位置和JSON语法 - 使用 Jsonlin.com 验证JSON - 确保已安装Node.js 18+

Windows上的“浏览器无法启动”

- 在中添加显式Chrome路径 executablePath - 尝试以管理员身份运行Cursor IDE - 检查Windows Defender是否阻止Chrome

“权限被拒绝”

- 使用 sudo npm install -g puppeteer-real-browser-mcp-server 在Linux/Mac上 - 在Windows上以管理员身份运行命令提示符

配置未加载

- 确保文件命名准确 mcp.json （不是 mcp.json.txt) - 检查文件是否在正确的目录中 - 更改后重新启动Cursor IDE

与其他AI助手

启动服务器：

puppeteer-real-browser-mcp-server

或者，如果从源代码安装：

npm start

服务器使用MCP协议通过stdin/stdout进行通信。

交互示例

基本Web浏览

User: "Initialize a browser and navigate to example.com"
AI: I'll initialize a stealth browser and navigate to the website.
[Uses browser_init and navigate tools]

表单自动化

User: "Fill in the search form with 'test query'"
AI: I'll type that into the search field.
[Uses type tool with selector and text]

User: "Click the search button"
AI: I'll click the search button.
[Uses click tool]

数据提取

User: "Get all the product names from this e-commerce page"
AI: I'll extract the product information from the page.
[Uses get_content tool with appropriate selectors]

User: "Save the page content as text"
AI: I'll get the text content of the entire page.
[Uses get_content tool with type: 'text']

User: "Save this page content as a markdown file"
AI: I'll extract the page content and save it as a formatted markdown file.
[Uses save_content_as_markdown tool with specified file path]

使用代理

User: "Initialize a browser with a proxy server"
AI: I'll set up the browser with your proxy configuration.
[Uses browser_init with proxy: "https://proxy.example.com:8080"]

可用工具

核心浏览器工具

工具名称	描述	必需参数	可选参数
`browser_init`	使用高级选项初始化隐形浏览器	无	`headless`, `disableXvfb`, `ignoreAllFlags`, `proxy`, `plugins`, `connectOption`
`navigate`	导航到URL	`url`	`waitUntil`
`get_content`	获取页面内容（HTML或文本）	无	`type`, `selector`
`browser_close`	关闭浏览器实例	无	无

交互工具

工具名称	描述	必需参数	可选参数
`click`	标准点击元素	`selector`	`waitForNavigation`
`type`	在输入框中键入文本	`selector`, `text`	`delay`
`wait`	等待各种条件	`type`, `value`	`timeout`
`find_selector`	查找包含特定文本的元素的CSS选择器	`text`	`elementType`, `exact`

行为工具

工具名称	描述	必需参数	可选参数
`random_scroll`	以自然定时执行随机滚动	无	无

元素发现工具

工具名称	描述	必需参数	可选参数
`find_selector`	查找包含特定文本的元素的CSS选择器	`text`	`elementType`, `exact`

内容工具

工具名称	描述	必需参数	可选参数
`save_content_as_markdown`	提取页面内容并将其保存为格式化的markdown文件	`filePath`	`contentType`, `selector`, `formatOptions`

反检测工具

工具名称	描述	必需参数	可选参数
`solve_captcha`	尝试解决验证码问题	`type`	没有

高级功能

动态选择器发现

服务器通过以下方式包括智能元素发现功能 find_selector 工具：

基于文本的元素查找：自动定位包含特定文本的元素
智能CSS选择器生成：创建类似于Chrome DevTools的独特、健壮的CSS选择器
元素类型过滤：可选择将搜索限制为特定的HTML元素（例如按钮、链接）
精确或部分文本匹配：在精确文本匹配或子字符串搜索之间进行选择
通用兼容性：适用于任何网站，无需硬编码选择器

示例用法：

User: "Find the submit button that says 'Sign Up'"
AI: I'll locate that button for you.
[Uses find_selector with text: "Sign Up", elementType: "button"]

AI: Found button at selector: "form > button.btn-primary:nth-of-type(2)"

这种方法消除了手动制作选择器的需要，并使自动化在不同网站之间更加可靠。

自然互动

该服务器包括为自然浏览行为设计的工具：

随机滚动：以自然时间和可变距离执行滚动

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

验证码处理

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

验证码
Hcaptcha
Cloudflare 验证码

请注意，验证码求解能力取决于底层 puppeteer真正的浏览器实现。

配置

自动Chrome路径检测（v1.3.0中增强）

服务器会自动检测不同操作系统之间的Chrome安装路径，并显著改进对Windows的支持：

Windows（v1.3.0+）:

- 基于注册表的已安装Chrome版本检测 - 搜索15个以上的常见安装目录，包括程序文件、用户特定位置和便携式安装 - 支持Chrome Canary回退 - 环境变量检测(CHROME_PATH, PUPPETEER_EXECUTABLE_PATH) - 找不到Chrome时的详细故障排除指南

macOS：在中查找Chrome /Applications/Google Chrome.app/ Chrome Canary的位置

Linux：检查多个位置，包括 /usr/bin/google-chrome, /usr/bin/chromium-browser，以及快速安装

Windows注册表检测 （v1.3.0中的新功能）：服务器现在查询Windows注册表以查找Chrome安装，使不同安装类型的检测更加可靠。

如果未自动找到Chrome，您可以使用以下命令指定自定义路径：

环境变量： set CHROME_PATH="C:\Your\Chrome\Path\chrome.exe"
浏览器初始化选项： customConfig.chromePath 初始化浏览器时

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

自定义选项，如无头模式 未在MCP配置文件中配置。相反，在使用 browser_init 工具：

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

Please initialize a browser with headless mode enabled and a 30-second timeout

克劳德将使用 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：60000（连接超时）

MCP配置文件只告诉Claude在哪里找到服务器-所有特定于浏览器的选项都是通过您与Claude的对话配置的。

浏览器选项示例

使用初始化浏览器时 browser_init，您可以配置：

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

高级配置示例

指定自定义Chrome路径

{
  "customConfig": {
    "chromePath": "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe"
  }
}

使用代理

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

具有自定义选项的隐形模式

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

服务器配置

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

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

故障排除

Windows主要连接问题（在v1.3.0中修复）

🔧 ECONNREFUSED错误解决方案

1.3.0版本包括对 connect ECONNREFUSED 127.0.0.1:60725 Windows系统上常见的错误：

增强的Chrome路径检测：

添加了基于Windows注册表的Chrome检测
将搜索范围扩展到15+个Windows安装位置，包括便携式安装
添加了对Chrome Canary回退的支持
环境变量支持(CHROME_PATH, PUPPETEER_EXECUTABLE_PATH)

Windows特定启动优化：

20多个特定于Windows的Chrome标志，以实现更好的兼容性
多种回退策略（5种不同的连接方法）
具有指数回退的渐进式重试逻辑
增强的超时处理（Windows为120秒，其他平台为90秒）

连接弹性特征：

本地主机与127.0.0.1回退处理（修复已知的Puppeteer问题）
端口可用性检查和自动端口分配
浏览器启动前的网络连接测试
增强的错误分类和自动回退策略

如果您仍然遇到ECONNREFUSED错误：

环境变量（推荐）：

   set CHROME_PATH="C:\Program Files\Google\Chrome\Application\chrome.exe"

手动Chrome路径配置：

   Ask Claude: "Initialize browser with custom Chrome path at C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe"

网络故障排除：

   # Test localhost resolution
   ping localhost
   # Should resolve to 127.0.0.1

   # Check Windows hosts file
   notepad C:\Windows\System32\drivers\etc\hosts
   # Ensure: 127.0.0.1 localhost

Chrome进程管理：

   # Kill existing Chrome processes
   taskkill /f /im chrome.exe

常见问题

npx具体问题

“spawn npx ENOENT”或“找不到命令”错误

- 原因： npx不在您的系统PATH中，或者Node.js安装不正确 - 解决： - 验证Node.js安装： node --version 和 npm --version - 从重新安装Node.js - 对于NVM用户，请参阅下面的NVM特定部分

在Claude Desktop/Cursor中“npx:找不到命令”

- 窗户： 确保在安装Node.js后重新启动IDE - Mac/Linux： 将npm添加到PATH： export PATH="$PATH:$(npm bin -g)" - 备选方案： 使用npx的完整路径： /usr/local/bin/npx

npx挂起或花费太长时间

- npx在第一次运行时下载包，这可能需要30-60秒 - 确保您有稳定的互联网连接 - 尝试清除npm缓存： npm cache clean --force

使用NVM（节点版本管理器）？

- 标准npx命令可能会在NVM中失败 - 解决方案1： 在配置中使用绝对路径：

     {
       "mcpServers": {
         "puppeteer-real-browser": {
           "command": "/Users/yourname/.nvm/versions/node/v20.0.0/bin/npx",
           "args": ["puppeteer-real-browser-mcp-server@latest"]
         }
       }
     }

- 解决方案2： 设置默认节点版本： nvm alias default 20.0.0

npx出现拒绝权限错误

- Mac/Linux： 尝试使用sudo： sudo npx puppeteer-real-browser-mcp-server@latest - 更好的解决方案： 修复npm权限： npm config set prefix ~/.npm

其他常见问题

“超过最大调用堆栈大小”错误

- 这在1.2.0版本中得到了修复，具有全面的堆栈溢出保护 - 服务器现在包括断路器模式和递归深度跟踪 - 超时控制可防止可能导致堆栈溢出的挂起操作 - 如果您遇到此错误，请确保您使用的是最新版本： npx puppeteer-real-browser-mcp-server@latest

使用npx时“找不到命令”或“语法错误”

- 在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

浏览器无法启动

- 检查Chrome/Chromium是否安装在标准位置

- Windows特定故障排除:

步骤1：验证Chrome安装路径 按顺序检查这些位置：

- C:\Program Files\Google\Chrome\Application\chrome.exe - C:\Program Files (x86)\Google\Chrome\Application\chrome.exe - %LOCALAPPDATA%\Google\Chrome\Application\chrome.exe - %PROGRAMFILES%\Google\Chrome\Application\chrome.exe

步骤2：手动路径配置 如果Chrome位于其他位置，请手动指定：

     Ask Claude: "Initialize browser with custom Chrome path at C:\Your\Chrome\Path\chrome.exe"

步骤3:Windows启动参数 为了与Windows兼容，请使用以下启动参数：

     Ask Claude: "Initialize browser with args --disable-gpu --disable-setuid-sandbox"

步骤4:Windows特定解决方案

- 以管理员身份运行：尝试以管理员身份运行IDE/终端 - Windows Defender：将Chrome和Node.js添加到Windows Defender排除项中 - 防病毒软件：暂时禁用防病毒软件，以测试它是否阻止Chrome - 用户账户控制：暂时降低UAC设置以进行测试 - Chrome进程：在任务管理器中终止所有现有的Chrome进程

步骤5：替代Chrome安装 如果Chrome检测仍然失败：

- 直接从以下网址下载Chrome google.com/chrome - 安装到默认位置(C:\Program Files\Google\Chrome\) - 安装后重新启动IDE

步骤6:PowerShell与命令提示符 尝试在PowerShell和命令提示符之间切换：

- 测试用 cmd.exe 而不是PowerShell - 使用PowerShell而不是命令提示符进行测试

步骤7：Node.js和npm配置

- 确保Node.js已添加到PATH中： node --version - 清除npm缓存： npm cache clean --force - 重新安装全局软件包： npm install -g puppeteer-real-browser-mcp-server@latest

- Linux：安装依赖项： sudo apt-get install -y google-chrome-stable

- macOS：确保Chrome处于 /Applications/

- 试试看 headless: true 第一

- 检查Chrome路径检测消息的控制台输出

Claude看不到MCP服务器

- 验证 claude_desktop_config.json 位置正确 - 检查JSON语法是否有效（使用 Jsonlin.com) - 完全重新启动克劳德桌面 - 检查Claude Desktop中是否有任何错误消息

4a。Claude Code CLI看不到MCP服务器

安装问题:

- 验证 claude mcp add 命令成功 - 检查命令语法： claude mcp add puppeteer-real-browser -- npx puppeteer-real-browser-mcp-server@latest - 确保您拥有最新的Claude Code CLI版本

范围和配置:

- 检查您使用的范围：本地（默认）、项目或用户 - 对于本地范围：确保您位于正确的项目目录中 - 对于项目范围：验证 .mcp.json 存在于项目根目录中 - 对于用户范围：检查用户配置目录

MCP服务器状态:

- 使用 /mcp Claude Code中用于检查服务器状态的命令 - 在列表中查找“木偶师真实浏览器”服务器 - 检查服务器状态是否显示“已连接”或错误消息

环境变量:

- 如果使用自定义环境变量（Chrome路径、代理），请验证它们是否设置正确 - 首先在没有环境变量的情况下进行测试： claude mcp add puppeteer-real-browser -- npx puppeteer-real-browser-mcp-server@latest

Node.js和npx问题:

- 验证Node.js 18+版本： node --version - 直接测试npx： npx puppeteer-real-browser-mcp-server@latest - 清除npm缓存： npm cache clean --force

协议版本问题 （已知问题）：

- 尽管配置正确，Claude CLI仍可能显示protocolVersion验证错误 - 这是Claude CLI内部验证的一个已知问题 - 尽管有验证警告，服务器仍可能工作

重新添加服务器:

  # Remove and re-add if issues persist
  claude mcp remove puppeteer-real-browser
  claude mcp add puppeteer-real-browser -- npx puppeteer-real-browser-mcp-server@latest

4b。游标IDE看不到MCP服务器

配置文件位置问题:

- 验证 mcp.json 位置正确： - 全球的： ~/.cursor/mcp.json (%USERPROFILE%\.cursor\mcp.json 在Windows上） - 项目： .cursor/mcp.json 在项目根目录中 - 确保文件名准确无误 mcp.json （不是 mcp.json.txt) - 检查文件权限是否允许读取

JSON语法验证:

- 使用 Jsonlin.com 验证JSON语法 - 常见问题：缺少逗号、引号不正确、尾随逗号 - 确保Windows路径的正确转义： "C:/Program Files/Google/Chrome/Application/chrome.exe"

游标IDE重新启动过程:

- 完全关闭Cursor IDE（检查Windows上的任务管理器） - 等待5秒 - 重新启动游标IDE - 打开命令面板，检查MCP服务器是否列出

环境变量:

- 验证Node.js是否可访问： node --version - 检查PATH是否包含npm： npm --version - 清除任何冲突的环境变量

游标IDE版本兼容性:

- 确保Cursor IDE版本支持MCP（最新版本） - 如果使用旧版本，请更新Cursor IDE - 检查Cursor IDE文档以了解MCP要求

权限被拒绝错误

- 在Linux/Mac上：试试 sudo npm install -g puppeteer-real-browser-mcp-server - 或者使用nvm管理Node.js而无需sudo - 在Windows上：以管理员身份运行命令提示符

检测问题

- 在操作之间使用适当的延迟，以提高可靠性 - 添加随机延迟 random_scroll - 如果需要，请使用代理： proxy: "http://proxy.example.com:8080"

内存泄漏

- 始终使用以下命令关闭浏览器实例 browser_close 完成后 - 不要在不关闭前一个浏览器的情况下初始化多个浏览器 - 检查可能阻止清理的未捕获异常

超时错误

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

常见问题

Q：我应该在什么时候使用npm install而不是npx？ A.

使用npx（推荐给大多数用户）： 与Claude Desktop、Claude Code CLI或Cursor IDE一起使用时。配置中的npx命令会自动下载并运行最新版本，无需安装。
使用npm install-g： 只有当你想经常直接从命令行运行服务器，或者你正在开发/为项目做出贡献时。
从不需要： 如果您只是Claude Desktop/Claude Code CLI用户，请按照快速入门指南进行操作，npx会处理一切！

Q：我应该使用Claude Desktop还是Claude Code CLI？ A：两者都是很好的选择，具体取决于您的需求：

克劳德桌面：

最适合： 简单的网页浏览自动化、内容提取、基本表单填写
设置： 手动JSON配置文件编辑
共享： 仅供个人使用
接口： 桌面GUI应用程序
身份验证： 无需

克劳德代码CLI：

最适合： 开发工作流程、团队协作、项目特定自动化
设置： 简单的命令行设置(claude mcp add)
共享： 通过项目范围支持团队共享
接口： 命令行与IDE集成
身份验证： OAuth支持可用
高级功能： 环境变量、范围控制、服务器监控

如果您有以下情况，请使用Claude Code CLI：

在开发团队工作
需要项目特定的浏览器自动化
需要环境变量配置
更喜欢命令行工作流
需要服务器健康监控

如果您有以下情况，请使用克劳德桌面：

想要简单的GUI体验
实现个人浏览自动化
不需要团队协作功能
比命令行更喜欢可视化界面

Q：为什么在npx命令中使用@latest？ A： The @latest 标签确保您始终获得包含错误修复和安全更新的最新版本。如果没有它，npx可能会缓存旧版本。这对于积极维护的项目尤为重要。

Q：这适用于无头浏览器吗？ A：是，设置 headless: true 在browser_init选项中。

Q：我可以同时使用多个浏览器吗？ A：目前支持一个浏览器实例。在开始新的之前，先关闭当前的。

Q：它能解决什么验证码？ A：通过木偶师真实浏览器支持reCAPTCHA、hCaptcha和Cloudflare旋转栅门。

Q：这能被网站检测到吗？ A： puppeteer真实浏览器包含反检测功能，但没有解决方案是100%无法检测到的。

Q：我可以使用自定义Chrome扩展程序吗？ A：是的，通过 plugins browser_init中的选项。

Q：它适用于所有操作系统吗？ A：是的，在Windows、macOS和Linux上进行了测试。服务器会自动检测所有平台上的Chrome安装。

Q： Claude Desktop、Claude Code CLI和Cursor IDE配置之间有什么区别？ A：下面是一个比较：

功能	克劳德桌面	克劳德代码CLI	光标IDE
设置方法	手动JSON编辑	命令行(`claude mcp add`)	一键安装或手动JSON
配置位置	`claude_desktop_config.json`	`.mcp.json` （范围）	`.cursor/mcp.json`
团队共享	否	是（项目范围）	是
环境变量	有限支持	全面支持	完全支持
范围控制	否	是（本地/项目/用户）	项目/全局
服务器监控	否	是(`/mcp` 命令）	有限
认证	无	OAuth可用	OAuth可用
最适合	个人GUI使用	开发团队	以代码为中心的工作流

命令示例：

克劳德桌面版：使用JSON编辑配置文件
Claude 代码命令行界面: claude mcp add puppeteer-real-browser -- npx puppeteer-real-browser-mcp-server@latest
光标IDE：一键安装或手动JSON配置

Q：如果Chrome安装在非标准位置怎么办？ A： 1.3.0版本显著提高了Chrome的检测能力。服务器现在搜索15多个位置，包括便携式安装，并使用Windows注册表检测。如果Chrome仍未自动找到，您可以：

设置环境变量： set CHROME_PATH="C:\Your\Chrome\Path\chrome.exe"
使用 customConfig.chromePath 选项： {"customConfig": {"chromePath": "C:\\Custom\\Chrome\\chrome.exe"}}

Q：为什么我在Windows上收到“找不到Chrome”或ECONNREFUSED错误？ A： 1.3.0版本包括对Windows Chrome检测和连接问题的全面修复。服务器现在会自动搜索这些位置以及更多内容：

C:\Program Files\Google\Chrome\Application\chrome.exe
C:\Program Files (x86)\Google\Chrome\Application\chrome.exe
%LOCALAPPDATA%\Google\Chrome\Application\chrome.exe
%USERPROFILE%\AppData\Local\Google\Chrome\Application\chrome.exe
Chrome Canary安装
便携式Chrome安装
注册表检测到安装

该服务器还实现了多种连接策略，在localhost和127.0.0.1之间自动回退，并增强了特定于Windows的Chrome标志，以实现更好的兼容性。

Q：升级到v1.3.0后，我仍然会收到ECONNREFUSED错误。我该怎么办？ A：按顺序尝试以下步骤：

设置 CHROME_PATH 环境变量到您的Chrome位置
删除所有现有的Chrome进程： taskkill /f /im chrome.exe
检查您的Windows主机文件是否包含： 127.0.0.1 localhost
尝试以管理员身份运行IDE
将Chrome添加到Windows Defender排除项
如果使用VPN/代理，请尝试暂时禁用它

调试模式

要启用调试日志记录，请执行以下操作：

DEBUG=true npm start

或者从源代码运行时：

DEBUG=true npm run dev

获取帮助

如果你仍然有问题：

检查
使用以下内容创建新问题：

- 您的操作系统 - Node.js版本(node --version) - npm版本(npm --version) - 完整错误消息 - 重现问题的步骤

发展

项目结构

puppeteer-real-browser-mcp-server/
├── src/
│   ├── index.ts         # Main server implementation
│   └── stealth-actions.ts # Browser interaction functions
├── test/
│   └── test-server.ts   # Test script
├── package.json
└── tsconfig.json

从源头构建

# Install dependencies
npm install

# Run in development mode
npm run dev

# Build for production
npm run build

# Test the server
npm test

添加新工具

要添加新工具，请执行以下操作：

将工具定义添加到 TOOLS 数组 src/index.ts
在中实现工具处理程序 CallToolRequestSchema 处理器
测试新工具功能

测试

该项目包括一个全面的测试套件，其中包含针对不同目的优化的多个类别：

快速测试（CI/CD）-约30秒

npm run test:quick    # Fast Jest tests for protocol compliance
npm test              # Alias for test:quick

综合测试-约5-10分钟

npm run test:full     # End-to-end MCP client testing

性能测试-约2-3分钟

npm run test:performance  # Browser performance benchmarking

性能测试测量：

浏览器初始化时间（5次试验）
跨不同站点类型的导航性能
并发操作处理
会话寿命测试（30秒以上30次操作）

调试工具-约10秒

npm run test:debug    # Environment diagnostics and troubleshooting

调试工具提供：

环境验证（Node.js版本、平台、内存）
具有特定路径的Chrome安装检测
具有启动时间的快速服务器健康检查
网络连接验证
构建状态验证

所有测试-约7-13分钟

npm run test:all      # Runs quick + full + performance tests
npm run test:dashboard # Unified test runner with reporting

测试仪表板提供：

统一执行多个测试类别
实时进度报告
绩效指标和时间安排
总体测试状态总结
失败测试的建议
JSON结果保存到 test-results/ 目录

集成测试

npm run test:integration  # Claude Code CLI integration testing

有关详细的测试信息，请参阅测试.md.

贡献

欢迎投稿！请随时提交拉取请求。

克隆该仓库
创建功能分支(git checkout -b feature/amazing-feature)
提交您的更改(git commit -m 'Add some amazing feature')
推到分支(git push origin feature/amazing-feature)
打开拉取请求

许可证

此项目根据MIT许可证获得许可-有关详细信息，请参阅许可证文件。

致谢

此MCP服务器基于木偶师真实浏览器 ZFC Digital的图书馆。

非常感谢。 感谢木偶师真实浏览器团队创建了如此强大且抗检测的浏览器自动化解决方案！

github：
npm：

Puppeteer Real Browser MCP Server

快速接入

详细介绍

Puppeter真实浏览器MCP服务器

目录

初学者快速入门

这是什么？

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

逐步设置

1.安装Node.js（必填）

2.配置克劳德桌面

3.重新启动克劳德桌面

4.测试它是否有效

你能用它做什么？

安全须知

介绍

特性

先决条件

平台特定要求

开发者安装

全局安装（用于命令行）

开发设置（供贡献者使用）

用法

使用克劳德桌面

使用Claude Code CLI

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

方法2：添加环境变量

方法3：范围配置

方法4:JSON配置

验证与测试

配置范围说明

Claude Code CLI的优点

使用游标IDE

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

方法2：手动配置

Cursor IDE的特定平台Chrome路径

测试游标IDE设置

游标IDE故障排除

与其他AI助手

交互示例

基本Web浏览

表单自动化

数据提取

使用代理

可用工具

核心浏览器工具

交互工具

行为工具

元素发现工具

内容工具

反检测工具

高级功能

动态选择器发现

自然互动

验证码处理

配置

自动Chrome路径检测（v1.3.0中增强）

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

可用浏览器选项

浏览器选项示例

高级配置示例

指定自定义Chrome路径

使用代理

具有自定义选项的隐形模式

服务器配置

故障排除

Windows主要连接问题（在v1.3.0中修复）

常见问题

npx具体问题

其他常见问题

常见问题

调试模式

获取帮助

发展

项目结构

从源头构建

添加新工具

测试

快速测试（CI/CD）-约30秒

综合测试-约5-10分钟