Puppeteer MCP

pptr-mcp

通过 Puppeteer 实现浏览器自动化的 MCP 服务。与其他提供固定工具（导航、点击、截图）的浏览器 MCP 服务不同，此服务可执行任意 JavaScript 代码，并直接访问 Puppeteer Browser 实例。

主要区别

大多数浏览器 MCP 服务都提供有限的预定义操作。这种方式在处理复杂工作流时需要多次往返，也无法处理边缘情况。

pptr-mcp 采用了不同的方式：它提供一个 execute 工具，可在 Node.js VM 中运行你的 JavaScript 代码，并提供全局变量 browser。你可以直接编写 Puppeteer 代码，在一次调用中访问完整 API。

Traditional MCP (5 round-trips)         pptr-mcp (1 round-trip)
================================        ================================

  Agent           Server                  Agent           Server
    |                |                      |                |
    |-- navigate --->|                      |-- execute ---->|
    |<-- ok ---------|                      |                |
    |                |                      |   +------------------------+
    |-- waitFor ---->|                      |   | const page = await     |
    |<-- ok ---------|                      |   |   browser.newPage();   |
    |                |                      |   | await page.goto(url);  |
    |-- click ------>|                      |   | await page.click(s);   |
    |<-- ok ---------|                      |   | await page.type(i, t); |
    |                |                      |   | return await           |
    |-- type ------->|                      |   |   page.screenshot();   |
    |<-- ok ---------|                      |   +------------------------+
    |                |                      |                |
    |-- screenshot ->|                      |<-- result -----|
    |<-- image ------|                      |                |
    |                |                      |                |

要求

• Node.js >= 20

安装

npm install -g pptr-mcp

MCP 配置

添加到你的 MCP 客户端配置中（例如 Claude Desktop）：

{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": ["pptr-mcp"]
    }
  }
}

使用 CLI 选项：

{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": ["pptr-mcp", "--no-headless", "--viewport=1080p"]
    }
  }
}

使用自定义 Chrome 标志（位于 -- 之后）：

{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": [
        "pptr-mcp",
        "--viewport=1280x720",
        "--",
        "--proxy-server=http://proxy:8080"
      ]
    }
  }
}

CLI 选项

选项	描述
--no-headless	显示浏览器窗口运行
--viewport=VALUE	设置视口大小（例如 1920x1080 或 1080p）
--help, -h	显示帮助
-- [args]	将剩余参数传递给 Chrome

-- 之前的未知选项也会传递给 Chrome。

Claude Code 插件

安装为 Claude Code 插件：

/plugin marketplace add iatsiuk/pptr-mcp
/plugin install pptr-mcp@pptr-mcp

环境变量

变量	描述
CHROME_PATH	Chrome 可执行文件的路径
PUPPETEER_EXECUTABLE_PATH	CHROME_PATH 的替代项
PUPPETEER_CACHE_DIR	浏览器下载缓存目录
PPTR_MCP_TIMEOUT	执行超时时间，单位为毫秒（默认值：30000）

工具：execute

执行可访问 Puppeteer 浏览器的 JavaScript 代码。

参数

名称	类型	默认值	描述
code	string	必填	要执行的 JavaScript 代码
persistent	boolean	true	在多次调用之间复用浏览器会话

示例

禁用无头模式

执行期间显示浏览器窗口：

{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": ["pptr-mcp", "--no-headless"]
    }
  }
}

自定义 Chrome 配置目录

使用你自己的 Chrome 配置，其中保存了登录信息和 Cookie：

{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": ["pptr-mcp", "--", "--user-data-dir=/path/to/profile"]
    }
  }
}

使用系统 Chrome，而非下载的版本

默认情况下，pptr-mcp 会下载 Chrome for Testing，这是一个针对捆绑的 Puppeteer 优化并经过测试的版本。若要改用系统 Chrome：

{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": ["pptr-mcp"],
      "env": {
        "CHROME_PATH": "/path/to/chrome"
      }
    }
  }
}

安全性

此服务专为使用大模型助手（Claude Code、Cursor 等）的可信本地开发而设计。执行的代码由你请求的大模型提供。

这意味着

• 不是沙箱：Node.js VM 是为方便使用而隔离代码，并非出于安全目的设计。它不适用于运行不可信代码。
• 完全控制浏览器：执行的代码可以导航到任意 URL、读取页面内容、截取屏幕截图并与 Web 应用交互。
• Chrome 在无沙箱模式下运行：为兼容 Docker/容器，会使用 --no-sandbox 标志。
• 持久会话：使用 persistent: true（默认值）时，Cookie 和浏览器状态会在多次调用之间保留。若要隔离，请使用 persistent: false。

不适用于

• 多租户或共享服务部署
• 执行来自外部来源的不可信代码
• 构建接受任意用户输入的 Web 服务

许可证

WTFPL