AI导哈

浏览器自动化服务

Puppeteer Real Browser MCP Server是一个本地Chrome浏览器自动化服务，通过Model Context Protocol (MCP)提供网页导航、内容读取和交互控制功能。

  • by withLinda
  • TypeScript
  • 本地部署
  • 26 星标
  • 更新于
在 GitHub 查看 withLinda/puppeteer-real-browser-mcp-server

使用说明

Puppeter真实浏览器MCP服务器

给MCP兼容的AI助手一个可以打开的本地Chrome浏览器， 导航、读取和控制。

正在维护中： 这个项目仍在变化。这 main 分支机构可以 比npm上发布的包更新。上面的npm徽章显示了 使用的已发布版本 @latest.

它做什么

此程序包作为本地程序运行 模型上下文协议（MCP） 服务器。您的MCP客户端启动服务器，服务器启动一个Chrome浏览器 浏览器自动化过程。

主要特点：

  • 默认情况下打开一个可见的浏览器，具有可选的无头模式
  • 浏览页面并读取HTML或文本
  • 查找元素、单击、键入、等待和滚动
  • 用途 rebrowser-puppeteer-core 以及一小部分反检测设置
  • 检测Windows、macOS和Linux上的Chrome
  • 支持自定义Chrome路径、代理和专用自动化配置文件
  • 跟踪它启动和关闭的确切Chrome进程
  • 在页面交互之前强制执行内容优先工作流

浏览器自动化是不可见的。网站仍可能检测到它或阻止它。

安全和电流限制

请在使用服务器之前阅读以下内容：

  • 仅在您被允许自动化的网站上使用它。
  • 在批准登录、表单、购买、下载或 其他敏感行为。
  • 浏览器和文件工具以您的正常用户权限运行。
  • 服务器一次支持一个浏览器会话。
  • solve_captcha 目前是一个占位符。它不使用验证码解决 服务。浏览器启动仅尽最大努力点击检测到的旋转栅门 小部件。
  • save_content_as_markdown 由服务器列出，但当前工作流 验证器会阻止它。这是一个已知的代码问题。

需求

  • Node.js 18或更新
  • npm和 npx （包含在普通的Node.js安装程序中）
  • 谷歌Chrome或Chromium
  • 可以启动本地的MCP客户端 stdio 服务器

Claude Desktop可在macOS和Windows上使用。其他MCP客户端可以使用 Linux上的这台服务器。

快速开始

您不需要全局安装此软件包。 npx 可以下载并运行 当您的MCP客户端需要时，提供已发布的包。

这 -y 选项可防止npm安装问题阻止MCP服务器 当它开始的时候。

克劳德桌面版

  1. 打开 克劳德桌面版→ 设置→ 开发者→ 编辑配置.
  2. 在内部添加此服务器 mcpServers:
{
  "mcpServers": {
    "puppeteer-real-browser": {
      "command": "npx",
      "args": [
        "-y",
        "puppeteer-real-browser-mcp-server@latest"
      ]
    }
  }
}
  1. 保存文件。
  2. 完全退出Claude Desktop，然后重新打开。

Claude Desktop将此文件存储在此处：

  • macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
  • 窗户： %APPDATA%\Claude\claude_desktop_config.json

见官方 本地MCP服务器指南 对于当前的Claude Desktop步骤。

Claude 代码

运行：

claude mcp add --transport stdio puppeteer-real-browser \
  -- npx -y puppeteer-real-browser-mcp-server@latest

然后检查连接：

claude mcp get puppeteer-real-browser

在克劳德密码内部， /mcp 还显示服务器状态。

默认范围是当前项目的本地范围。加 --scope user 之前 如果您希望在所有项目中使用服务器，请提供服务器名称。见官方 克劳德代码MCP指南 了解范围详细信息。

光标

创建 .cursor/mcp.json 在一个项目中，或 ~/.cursor/mcp.json 对于所有 项目：

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

保存文件后重新启动Cursor。见官方 光标MCP指南 为了 当前配置位置和格式。

其他MCP客户端

使用本地 stdio 带有此命令和参数列表的服务器：

command: npx
args: -y puppeteer-real-browser-mcp-server@latest

服务器通过标准输入和标准输出进行通信。您的MCP 客户端在使用工具时必须保持流程打开。

测试设置

问你的AI助手：

启动浏览器，打开 https://example.com，阅读页面文本，然后 关闭浏览器。

预期的工具订单为：

browser_init → navigate → get_content → browser_close

可用工具

服务器公开了11个工具。

工具 目的 所需输入
browser_init 启动或重新使用托管Chrome会话 无
navigate 打开URL url
get_content 阅读整页或所选HTML/文本 无
find_selector 从元素文本中查找CSS选择器 text
click 单击元素 selector
type 清除并键入输入 selector, text
wait 等待选择器、导航或时间 type, value
random_scroll 滚动不同的时间和距离 无
solve_captcha 返回占位符尝试结果 type
save_content_as_markdown 另存为 .md；当前被阻止 filePath
browser_close 关闭托管浏览器并重置工作流状态 无

内容优先的工作流程

服务器阻止盲目交互。使用以下顺序：

browser_init → navigate → get_content → find_selector → click or type

在新的导航后，呼叫 get_content 再次单击或键入之前。 你可以打电话 wait 导航后，页面加载内容缓慢。

浏览器配置

浏览器选项是输入 browser_init。它们不是顶级MCP 服务器设置。

选项 含义
headless 设置 true 隐藏浏览器窗口。违约： false.
proxy 代理URL，例如 http://proxy.example.com:8080.
profilePath 专用自动化配置文件路径。
disableXvfb 设置 false 在Linux上启动Xvfb。
connectOption.timeout 连接和设置超时（毫秒）
connectOption.slowMo 延迟操作（毫秒）
customConfig.chromePath Chrome可执行文件的绝对路径。
customConfig.chromeFlags 自定义旗帜；替换服务器标志列表。
contentPriority 内容优先级建议设置。

contentPriority 是一个对象 prioritizeContent 和 autoSuggestGetContent 布尔值。它改变了建议，但没有 先删除所需内容工作流。

请求示例：

{
  "headless": true,
  "proxy": "http://proxy.example.com:8080",
  "connectOption": {
    "timeout": 60000,
    "slowMo": 100
  },
  "customConfig": {
    "chromePath": "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
  }
}

Chrome路径

服务器首先检查这些环境变量：

  1. CHROME_PATH
  2. PUPPETEER_EXECUTABLE_PATH

如果两者都不指向文件，服务器将检查常见的Chrome和Chromium 位置。在Windows上，它还会检查注册表和常见的可移植路径。

您可以设置 CHROME_PATH 在MCP客户端配置中：

{
  "mcpServers": {
    "puppeteer-real-browser": {
      "command": "npx",
      "args": [
        "-y",
        "puppeteer-real-browser-mcp-server@latest"
      ],
      "env": {
        "CHROME_PATH": "/absolute/path/to/chrome"
      }
    }
  }
}

PROXY_URL 不是受支持的环境变量。将代理传递给 browser_init 相反。

浏览器所有权保护

服务器保留Chrome的确切启动器句柄和进程ID 过程开始了。正常关闭、启动失败、超时、MCP断开连接，以及 信号关机所有清理通过那个手柄。它不搜索或 按进程名称关闭Chrome。

为了安全起见，服务器拒绝可能附加到其他浏览器的设置 或拥有个人Chrome个人资料：

  • customConfig.userDataDir
  • customConfig.port
  • customConfig.portStrictMode
  • customConfig.handleSIGINT
  • connectOption.browserURL
  • connectOption.browserWSEndpoint
  • connectOption.transport
  • --remote-debugging-port, --remote-debugging-pipe，以及 --user-data-dir 自定义Chrome标志内

使用 profilePath 用于持久自动化数据。目录必须是 绝对值，为空或已标记为此服务器拥有。

故障排除

MCP服务器未出现

  1. 检查工具是否已安装：

    node --version
npm --version
npx --version

  2. 检查Node.js是否为版本18或更高版本。

  3. 检查JSON文件是否缺少逗号或引号。

  4. 完全退出并重新打开MCP客户端。

  5. 如果桌面应用程序找不到 npx，将其绝对路径用作 command. 跑 which npx 在macOS/Linux或 where npx 在Windows上找到它。

Claude Desktop日志存储在此处：

  • macOS： ~/Library/Logs/Claude
  • 窗户： %APPDATA%\Claude\logs

未找到Chrome

找到真正的Chrome可执行文件，然后设置 CHROME_PATH 在MCP客户端中 配置。常见的例子有：

  • 窗户： C:/Program Files/Google/Chrome/Application/chrome.exe
  • macOS： /Applications/Google Chrome.app/Contents/MacOS/Google Chrome
  • Linux： /usr/bin/google-chrome 或 /usr/bin/chromium

不要以管理员身份运行MCP客户端或使用 sudo npm install -g 只为 解决Chrome路径问题。

在终端中运行时，服务器看起来卡住了

这可能是正常的。A. stdio MCP服务器等待来自MCP的协议消息 客户。使用MCP检查器，而不是在流程中键入。

测试已发布的包：

npx -y @modelcontextprotocol/inspector \
  npx puppeteer-real-browser-mcp-server@latest

见官方 MCP检查员指南 了解使用详情。

页面操作被阻止

遵循所需的工作流程：

  1. browser_init
  2. navigate
  3. get_content
  4. find_selector 当你需要一个选择器时
  5. click 或 type

如果页面更改，请致电 get_content 再一次。

浏览器连接超时

  • 检查Chrome路径是否存在。
  • 使用以下命令关闭当前托管浏览器 browser_close，然后重新开始。
  • 增加 connectOption.timeout 在 browser_init 输入。
  • 检查安全软件是否阻止了子Chrome进程。
  • 报告问题时包含完整的错误消息。

获取帮助

搜索或打开 GitHub问题. 包括：

  • 操作系统
  • Node.js和npm版本
  • MCP客户端名称和版本
  • Chrome版本和可执行路径
  • 完整错误消息
  • 重现问题的确切步骤

不包括密码、Cookie、令牌或私人页面内容。

发展

从源代码运行

git clone https://github.com/withLinda/puppeteer-real-browser-mcp-server.git
cd puppeteer-real-browser-mcp-server
npm ci
npm run build

使用MCP检查器测试本地构建：

npx -y @modelcontextprotocol/inspector node dist/index.js

要在MCP客户端中使用本地构建，请使用绝对路径：

{
  "mcpServers": {
    "puppeteer-real-browser-local": {
      "command": "node",
      "args": [
        "/absolute/path/to/puppeteer-real-browser-mcp-server/dist/index.js"
      ]
    }
  }
}

项目结构

src/index.ts                     MCP stdio server and request handlers
src/tool-definitions.ts          Tool names and input schemas
src/browser-manager.ts           Browser state, detection, and configuration
src/managed-browser-session.ts   Owned Chrome launch and cleanup
src/handlers/                    Tool implementations
src/*.test.ts                    Unit and regression tests
test/integration/                MCP protocol integration tests
test/e2e/                        Real-browser tests
test/safety/                     Browser cleanup safety guard
scripts/check-packaged-server.ts Package smoke test

测试工作流程

使用TDD进行行为更改：编写一个失败的测试，使其通过，然后进行清理 升级代码。

# Browser cleanup safety guard
npm run test:safety

# Fast source tests
npm run test:unit

# MCP protocol integration tests
npm run test:integration

# Build the package
npm run build

# Test the built npm package shape and stdio lifecycle
npm run test:package:smoke:built

# Real Chrome tests
npm run test:e2e

# Release-focused automated checks
npm run test:all

TDD期间，使用 npm run test:watch。在运行真正的浏览器测试之前，请注意 Chrome进程已在您的计算机上打开。测试后，验证 只有测试启动的Chrome进程被关闭。

贡献

欢迎问题和拉取请求。对于代码更改：

  1. 创建一个专注的分支。
  2. 为一个行为添加失败测试。
  3. 进行通过测试的最小代码更改。
  4. 在测试保持绿色时进行重构。
  5. 运行安全、源代码、构建和包检查。
  6. 解释提交中的根本原因、解决方案、预防措施和验证 消息。

许可证

该项目使用 MIT 许可证.

致谢

最初的实现和公共API基于 puppeteer-real-browser ZFC Digital。当前源取代了生命周期结束时的依赖关系 内置内部管理启动器 chrome-launcher, rebrowser-puppeteer-core，以及 ghost-cursor.

相关 MCP