Puppeteer Real Browser MCP Server

Puppeteer Real Browser MCP 服务

为兼容 MCP 的 AI 助手提供一个本地 Chrome 浏览器，让它能够打开、导航、读取和控制。

维护中： 该项目仍在变动。main 分支可能比 npm 上发布的包更新。上方的 npm 徽章显示的是 @latest 所使用的已发布版本。

功能简介

该包作为本地 Model Context Protocol (MCP) 服务运行。你的 MCP 客户端启动该服务，服务会启动一个 Chrome 进程用于浏览器自动化。

主要功能：

• 默认打开可见浏览器，可选无头模式
• 导航页面并读取 HTML 或文本
• 查找元素、点击、输入、等待和滚动
• 使用 rebrowser-puppeteer-core 及少量反检测设置
• 在 Windows、macOS 和 Linux 上检测 Chrome
• 支持自定义 Chrome 路径、代理和专用自动化配置文件
• 跟踪其启动的确切 Chrome 进程，并仅关闭该进程
• 在页面交互前强制执行内容优先的工作流

没有浏览器自动化是完全不可见的。网站仍可能检测到它或将其屏蔽。

安全性和当前限制

使用该服务前请阅读以下内容：

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

要求

• Node.js 18 或更新版本
• npm 和 npx（随常规 Node.js 安装程序提供）
• Google Chrome 或 Chromium
• 一个能够启动本地 stdio 服务的 MCP 客户端

Claude Desktop 可在 macOS 和 Windows 上使用。其他 MCP 客户端可在 Linux 上使用该服务。

快速开始

你无需全局安装该包。当你的 MCP 客户端需要时，npx 可以下载并运行已发布的包。

-y 选项可防止 npm 安装询问在 MCP 服务启动时阻塞。

Claude Desktop

1. 打开 Claude Desktop → Settings → Developer → Edit Config。
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
• Windows：%APPDATA%\Claude\claude_desktop_config.json

有关当前的 Claude Desktop 步骤，请参阅官方的本地 MCP 服务指南。

Claude Code

运行：

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

然后检查连接：

claude mcp get puppeteer-real-browser

在 Claude Code 中，/mcp 也会显示服务状态。

默认范围是当前项目本地。如果你希望该服务在所有项目中可用，请在服务名称前添加 --scope user。有关范围详细信息，请参阅官方的 Claude Code MCP 指南。

Cursor

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

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

保存文件后重新启动 Cursor。有关当前的配置位置和格式，请参阅官方的 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	连接和设置超时时间，单位为 ms。
connectOption.slowMo	操作延迟时间，单位为 ms。
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 上，它还会检查注册表和常见的便携式路径。

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

{
  "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
• 自定义 Chrome 标志中的 --remote-debugging-port、--remote-debugging-pipe 和 --user-data-dir

使用 profilePath 来保存持久化自动化数据。该目录必须是绝对路径，并且要么为空，要么已标记为归该服务所有。

故障排查

MCP 服务未显示

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

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

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

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

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

5. 如果桌面应用找不到 npx，请将其绝对路径用作 command。 在 macOS/Linux 上运行 which npx，在 Windows 上运行 where npx 来找到它。

Claude Desktop 日志存储在这里：

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

找不到 Chrome

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

• Windows：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

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

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

这可能是正常的。stdio MCP 服务会等待来自 MCP 客户端的协议消息。请使用 MCP Inspector，而不是向该进程输入内容。

测试已发布的包：

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

有关使用详情，请参阅官方 MCP Inspector 指南。

页面操作被阻止

请遵循所需的工作流：

1. browser_init
2. navigate
3. get_content
4. 需要选择器时使用 find_selector
5. click 或 type

如果页面发生了变化，请再次调用 get_content。

浏览器连接超时

• 检查 Chrome 路径是否存在。
• 使用 browser_close 关闭当前受管理的浏览器，然后再次启动它。
• 增大 browser_init 输入中的 connectOption.timeout。
• 检查安全软件是否正在阻止子 Chrome 进程。
• 报告问题时请附上完整的错误消息。

获取帮助

搜索或提交一个 GitHub issue。 请包含：

• 操作系统
• 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 Inspector 测试本地构建：

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 进程。

贡献

欢迎提交 issue 和 pull request。对于代码变更：

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

许可证

本项目使用 MIT 许可证。

致谢

最初的实现和公共 API 基于 ZFC Digital 的 puppeteer-real-browser。 当前源码用基于 chrome-launcher、 rebrowser-puppeteer-core 和 ghost-cursor 构建的内部受管理启动器替换了那个已终止生命周期的运行时依赖。