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

最新推荐文章于 2025-06-27 15:58:43 发布

佑瞻

最新推荐文章于 2025-06-27 15:58:43 发布

阅读量2.6k

点赞数 40

CC 4.0 BY-SA版权

分类专栏：工具与生态文章标签：浏览器自动化 python

本文链接：https://blog.csdn.net/The_Thieves/article/details/147550242

工具与生态专栏收录该内容

22 篇文章

订阅专栏

在浏览器自动化领域，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 环境下检查器会实时同步日志内容。