用 Puppeteer 搭建 MCP 服务器：功能详解与 npx 启动全攻略

在浏览器自动化领域，Puppeteer 凭借其强大的 API 和灵活的配置能力，成为开发者实现网页交互、截图、脚本执行的首选工具。本文将在详细介绍 Puppeteer MCP 服务器核心功能的基础上，重点解析如何通过npx 快速启动，让本地开发与调试更加便捷高效。

一、核心功能：打造全场景浏览器自动化工具箱

在深入启动配置前，我们先梳理 Puppeteer MCP 服务器提供的核心能力，这些功能覆盖了从基础导航到复杂脚本执行的全流程操作。

1. 网页操作工具集

• puppeteer_navigate：核心导航工具，支持传入url指定目标地址。

  json

  {
  "url": "https://example.com", // 必传，目标网页URL
  "launchOptions": { "headless": false }, // 可选，配置浏览器启动参数（npx默认非无头模式，会显示浏览器窗口）
  "allowDangerous": false // 可选，默认禁止危险启动参数，保障本地安全
  }
   

  npx 场景优势：启动后直接打开可视化浏览器窗口，实时观察导航效果，方便调试页面加载异常等问题。

• puppeteer_screenshot：支持整页或元素截图，name为截图唯一标识。

  json

  {
  "name": "homepage_screenshot", // 必传，截图名称
  "selector": "#main-content", // 可选，指定元素截图（npx环境下可通过浏览器窗口直观定位元素）
  "width": 1280, // 可选，自定义截图宽度（npx默认800，本地调试可按需调整）
  "height": 720 // 可选，自定义截图高度
  }

• 交互工具矩阵：包括click（点击）、fill（填充表单）、select（下拉选择）、hover（悬停）等，均通过 CSS 选择器定位元素，完美覆盖前端调试常见场景。例如填充输入框：

  json

  {
  "selector": "#search-input", // 输入框选择器
  "value": "puppeteer tutorial" // 填充内容
  }

• puppeteer_evaluate：执行自定义 JavaScript，支持获取页面数据或操作 DOM。

  json

  {
  "script": "document.title" // 执行后返回页面标题
  }
   

  npx 优势：配合可视化窗口，可即时验证脚本执行效果，避免无头模式下的盲目调试。

2. 资源管理能力

• 服务器为我们提供了两种重要的资源，方便我们对浏览器的状态和操作结果进行监控和使用。

   控制台日志：console://logs

  通过这个资源，我们可以获取浏览器控制台的输出信息，这些信息以文本格式呈现，包括浏览器运行过程中产生的所有控制台消息。我们可以利用这些日志来调试我们的操作，查看页面的运行状态，及时发现和解决问题。

   截图资源：screenshot://<name>

  我们通过puppeteer_screenshot工具捕获的截图会以 PNG 图像的形式存储为资源，每个截图可以通过在捕获时指定的名称来访问。例如，如果我们在截图时将名称设置为 "homepage"，那么就可以通过screenshot://homepage来获取这张截图。

二、npx 启动：本地开发的黄金搭档

接下来重点讲解如何通过 npx 快速启动服务器，享受可视化调试的便利。npx 无需全局安装，直接调用本地依赖，尤其适合临时项目或快速验证场景。

1. 初始化项目（首次使用必做）

bash

mkdir my-puppeteer-project && cd $_ # 创建并进入项目目录
npm init -y # 生成package.json（记录依赖，方便后续管理）

• npm init -y会自动生成默认配置的package.json，后续安装的@modelcontextprotocol/server-puppeteer会记录在dependencies中。

2. 安装核心依赖

bash

npm install @modelcontextprotocol/server-puppeteer # 安装服务器包及所有依赖

安装完成后，可通过以下方式验证：

• 检查node_modules/@modelcontextprotocol/server-puppeteer目录是否存在；
• 查看package.json中是否包含对应依赖项。

3. 一键启动服务器（带可视化窗口）

bash

npx @modelcontextprotocol/server-puppeteer # 启动命令

• 启动效果：自动打开 Chrome 浏览器窗口（非无头模式），控制台输出服务器连接状态及工具列表，提示Ready to accept requests即表示启动成功。
• 调试优势：所有页面操作（如点击、填充）都会在浏览器窗口中可视化执行，实时反馈操作结果，比无头模式更适合前端交互调试。

4. 搭配检查器增强调试（可选）

若需图形化查看工具调用日志和资源列表，可同时启动 MCP 官方检查器：

bash

npm install @modelcontextprotocol/inspector
npx @modelcontextprotocol/inspector npx -y @modelcontextprotocol/server-puppeteer # 检查器+服务器一键启动

• -y参数：自动确认安装检查器依赖，避免手动输入yes；
• 检查器界面可实时显示工具返回结果（如截图预览、控制台日志文本），适合新手快速定位问题。

三、VS Code 配置：提升 npx 开发效率

对于习惯 VS Code 的开发者，可通过以下配置实现无缝集成：

1. 用户设置（全局生效）

按下Ctrl + Shift + P打开命令面板，搜索并打开settings.json（用户设置 JSON），添加：

json

{
"mcp": {
"servers": {
"puppeteer": {
"command": "npx", // 使用npx执行命令
"args": ["-y", "@modelcontextprotocol/server-puppeteer"] // 自动确认依赖，启动服务器
}
}
}
}

• 配置后，VS Code 的 MCP 插件可直接识别服务器，支持通过插件界面一键启动，无需手动输入命令。

2. 工作区配置（项目级共享）

在项目根目录创建.vscode/mcp.json（团队协作推荐）：

json

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

• 此配置仅在当前项目生效，避免全局设置冲突，适合多人协作时统一开发环境。

四、npx 高级配置：定制化浏览器行为

1. 通过环境变量调整启动参数（全局生效）

若需自定义浏览器窗口大小、指定 Chrome 路径等，可在 npx 启动时添加环境变量：

json

{
"mcpServers": {
"puppeteer": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-puppeteer"],
"env": {
"PUPPETEER_LAUNCH_OPTIONS": "{\\"args\\":[\\"–window-size=1920,1080\\"]}", // 设置窗口尺寸
"ALLOW_DANGEROUS": "true" // 允许危险参数（如–no-sandbox，本地调试慎用）
}
}
}
}

• PUPPETEER_LAUNCH_OPTIONS：支持 Puppeteer 完整的LaunchOptions，如headless（npx 默认false，显示窗口）、executablePath（指定本地 Chrome 路径）。

2. 工具调用时动态覆盖配置（单次生效）

在调用puppeteer_navigate时，可临时传入launchOptions，优先级高于全局配置：

json

{
"url": "https://github.com",
"launchOptions": {
"headless": true, // 临时设为无头模式（覆盖npx默认的可视化窗口）
"defaultViewport": { "width": 1024, "height": 768 } // 临时设置视口尺寸
}
}

• 注意：若launchOptions与上次调用不同，服务器会自动重启浏览器以应用新配置，npx 环境下重启过程会显示浏览器窗口重新加载。

五、npx 启动常见问题与解决方案

1. 浏览器窗口未弹出？

• 原因 1：全局或工具调用中设置了headless: true。 解决：检查配置中的launchOptions，确保headless为false（npx 默认值）。
• 原因 2：Puppeteer 依赖的 Chromium 未正确安装。 解决：删除node_modules后重新安装依赖，或通过PUPPETEER_EXECUTABLE_PATH指定本地 Chrome 路径。

2. 危险参数报错（Dangerous arguments detected）

• 原因：配置中包含–no-sandbox等风险参数，且allowDangerous为false（默认值）。 解决：本地调试建议保持默认安全策略（不允许危险参数），确有需要时设置allowDangerous: true，并确保操作在可控环境中进行。

3. 如何查看截图和日志？

• 截图：通过puppeteer_screenshot工具的name参数生成后，可在 MCP 检查器中直接预览，或通过curl http://localhost:端口/screenshot://<name>获取二进制数据。
• 日志：控制台日志存储在console://logs，可通过服务器提供的ReadResource接口读取，npx 环境下检查器会实时同步日志内容。

六、为什么选择 npx 启动？

• 零配置成本：无需全局安装，直接调用本地依赖，适合快速验证想法或临时项目。
• 可视化调试：默认打开浏览器窗口，操作过程一目了然，大幅降低前端交互调试难度。
• 灵活扩展：支持通过环境变量或工具参数动态调整浏览器配置，适配不同调试场景。

通过 npx 启动 Puppeteer MCP 服务器，我们既能享受全功能的浏览器自动化能力，又能借助可视化窗口和便捷的配置，让开发调试效率提升一个台阶。如果你在使用过程中遇到问题，欢迎在评论区留言交流！

觉得本文实用的话，别忘了点赞收藏，关注我们获取更多 MCP 服务器开发和 Puppeteer 实战技巧，让浏览器自动化开发更简单高效！