Puppeteer MCP Server已精选

什么是 Puppeteer MCP Server？

Puppeteer MCP Server 是 Model Context Protocol 最初的参考服务器，借助 Puppeteer 让 AI 助手驱动真实的 Chromium 浏览器：打开网页、点击、填写表单、截图和运行 JavaScript。它现已归档，其 npm 包也被标记为不再支持。

该服务器由 Model Context Protocol 项目以 @modelcontextprotocol/server-puppeteer 发布，原本位于 modelcontextprotocol/servers 仓库，现已迁移到 modelcontextprotocol/servers-archived。该仓库说明，归档的服务器不再维护，也不提供任何安全保证。这个包仍然可以安装和运行，因此许多现有配置和教程仍在使用它；但对于新项目，通常更适合选择仍在积极维护的浏览器服务器（见下文的替代方案）。

如何使用 Puppeteer MCP Server？

前置条件：Node.js（用于 npx）或 Docker。无需 API key 或账号，浏览器运行在你自己的机器上。

README 介绍了两种运行 Puppeteer MCP server 的方式：

• NPX：会在桌面上打开一个可见的浏览器窗口。
• Docker（mcp/puppeteer 镜像）：在容器中运行无头 Chromium。

NPX 配置（与本页显示的配置相同）：

{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-puppeteer"]
    }
  }
}

Docker 配置：

{
  "mcpServers": {
    "puppeteer": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "--init", "-e", "DOCKER_CONTAINER=true", "mcp/puppeteer"]
    }
  }
}

Claude Code

使用 Claude Code CLI 注册这个 stdio 服务器：

claude mcp add puppeteer -- npx -y @modelcontextprotocol/server-puppeteer

Claude Desktop

将上面任一 JSON 配置添加到 claude_desktop_config.json 的 mcpServers 下，然后重启 Claude Desktop。

Cursor

Cursor 使用相同的 mcpServers 格式。把 NPX 配置放入 ~/.cursor/mcp.json（全局）或 .cursor/mcp.json（项目级）。

VS Code

README 提供了 NPX 和 Docker 的一键安装链接。手动配置时，将服务器添加到工作区的 .vscode/mcp.json（这里不需要外层的 mcp 键）：

{
  "servers": {
    "puppeteer": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-puppeteer"]
    }
  }
}

启动选项

你可以通过 PUPPETEER_LAUNCH_OPTIONS 环境变量（JSON 字符串）自定义浏览器，也可以在调用 puppeteer_navigate 工具时传入 launchOptions。会削弱安全性的参数（如 --no-sandbox 或 --disable-web-security）默认会被拒绝，除非将 ALLOW_DANGEROUS 设为 "true"（或在工具调用中传入 allowDangerous: true）：

"env": {
  "PUPPETEER_LAUNCH_OPTIONS": "{ \"headless\": false, \"executablePath\": \"C:/Program Files/Google/Chrome/Application/chrome.exe\", \"args\": [] }",
  "ALLOW_DANGEROUS": "true"
}

Puppeteer MCP Server 的主要功能

• 通过 Puppeteer 实现真实的浏览器自动化，用自然语言在 AI 客户端中控制。
• 七个工具，覆盖导航、点击、悬停、填写表单、<select> 选择、截图和执行 JavaScript。
• 可截取整页或单个元素（通过 CSS 选择器），宽高可配置，并可选择输出 base64。
• 浏览器控制台输出作为 MCP 资源 console://logs 提供。
• 已截取的截图作为资源 screenshot://<name> 提供。
• 可自定义启动选项，并对危险的 Chromium 参数做了防护。
• 本地运行，无需 API key，可选择可见浏览器（NPX）或 Docker 中的无头模式。

Puppeteer MCP Server 工具

该服务器提供七个工具，分为三组：

• 导航与页面状态： puppeteer_navigate 打开 URL，并可使用新的 launchOptions 重启浏览器。
• 交互： puppeteer_click、puppeteer_hover、puppeteer_fill 和 puppeteer_select 通过 CSS 选择器定位元素进行操作，可覆盖大多数登录表单、搜索框和下拉菜单。
• 检查： puppeteer_screenshot 截取页面或单个元素，puppeteer_evaluate 在页面中运行任意 JavaScript，适合读取 DOM 值或抓取其他工具无法获取的文本。

Puppeteer MCP Server 的使用场景

• 编码时做视觉检查： “打开 http://localhost:3000，截取页头的截图，告诉我 logo 是否没对齐。”
• 表单测试： “进入注册页面，填写邮箱和密码，点击提交，并报告出现的错误信息。”
• 轻量网页抓取： “打开这个商品页面，用 JavaScript 返回价格和标题。”
• 调试前端错误： 让助手加载页面并读取 console://logs 资源，找出 JavaScript 错误。
• 复现 bug 报告： 按顺序执行一系列点击和下拉选择，并在每一步截图。

Puppeteer MCP Server 与替代方案对比

由于 Puppeteer MCP server 已归档，了解仍在维护的选项会很有帮助：

• Playwright MCP Server：由 Microsoft 提供，基于页面的无障碍快照而不是截图和 CSS 选择器工作，支持多种浏览器，并在积极开发中。它是最常见的替代品。
• Chrome DevTools MCP：由 Chrome DevTools 团队提供，底层使用 Puppeteer，并增加了性能追踪、网络请求分析以及带 source map 堆栈的控制台消息。
• BrowserTools MCP Server：通过扩展连接你现有的 Chrome，适合需要从已打开的浏览器获取日志和审计结果的场景。

只有当现有工作流依赖其确切的工具名称，或需要极简的七工具接口时，才主要考虑使用原版 Puppeteer 服务器。

Puppeteer MCP Server 常见问题排查

• npm 显示 “Package no longer supported”： 这是正常的。服务器已归档，因此该包被弃用；它仍可运行，但你可能更适合选用上面的替代方案。
• 没有出现浏览器窗口： Docker 镜像运行的是无头 Chromium。如果想看到浏览器，请使用 NPX 配置，或在 PUPPETEER_LAUNCH_OPTIONS 中设置 "headless": false。
• “危险”启动参数报错： --no-sandbox 等参数默认被阻止。可将 ALLOW_DANGEROUS 设为 "true" 或传入 allowDangerous: true，但要清楚这会降低浏览器安全性。
• Chrome 版本不对或找不到： 在 PUPPETEER_LAUNCH_OPTIONS 中将 executablePath 指向你已安装的 Chrome。
• VS Code 中看不到工具： 在 .vscode/mcp.json 中使用顶层 servers 键；额外的 mcp 外层仅用于用户设置文件。