Puppeteer MCP Server

🚀 Puppeteer MCP 服务器文档

Puppeteer MCP 服务器借助 Puppeteer 工具库，通过 WebDriver 协议控制 Chrome 浏览器。它提供了丰富的 API 来操作浏览器，可实现导航、截图、元素操作等功能，为浏览器自动化操作提供了便利。

🚀 快速开始

Puppeteer 是一个由 Google 开发的工具库，用于通过 WebDriver 协议控制 Chrome 浏览器。Puppeteer 提供了丰富的 API 来操作浏览器，包括导航、截图、元素操作等。

✨ 主要特性

• 支持标准模式和活动标签模式，可灵活启动新浏览器实例或连接现有 Chrome 窗口。
• 提供多种工具，如连接现有 Chrome 实例、导航、截图、元素点击、表单填写与提交等。
• 支持自定义浏览器配置和扩展加载，增强浏览器功能。
• 具备完善的日志记录和错误处理机制。

📦 安装指南

标准安装

运行以下命令以克隆仓库并安装依赖项：

git clone https://github.com/your-repository.git
cd puppeteer-mcp-server
npm install

开发环境配置

1. 确保已安装 Node.js (版本 14 或更高) 和 npm。
2. 安装项目依赖：

   npm install
   

3. 启动开发服务器：

   npm run dev
   

生产环境部署

1. 安装项目依赖：

   npm install --production
   

2. 启动生产服务器：

   npm start
   

💻 使用示例

标准模式

默认情况下，服务器将启动一个新的浏览器实例。

活动标签模式

要连接到现有 Chrome 窗口：

1. 完全关闭所有现有的 Chrome 实例。
2. 启动 Chrome 时启用远程调试：

   # Windows
   "C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222
   
   # macOS
   /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222
   
   # Linux
   google-chrome --remote-debugging-port=9222
   

3. 在 Chrome 中导航到所需的网页。
4. 使用 puppeteer_connect_active_tab 工具连接：

   {
     "targetUrl": "https://example.com", // 可选：指定要连接的标签页 URL
     "debugPort": 9222 // 可选：默认为 9222
   }
   

服务器将：

• 检测并连接到运行中带有远程调试功能的 Chrome 实例。
• 保持你的 Chrome 实例（不会关闭它）。
• 查找并连接非扩展标签页。
• 在连接失败时提供清晰的错误消息。

📚 详细文档

可用工具

puppeteer_connect_active_tab

连接到现有 Chrome 实例，该实例启用了远程调试功能。

• 可选参数：
  • targetUrl：要连接的特定标签页的 URL。
  • debugPort：Chrome 调试端口（默认为 9222）。

puppeteer_navigate

导航到指定 URL。

• 必需参数：
  • url：要导航到的 URL。

puppeteer_screenshot

拍摄当前页面或特定元素的截图。

• 必需参数：
  • name：截图的名称。
• 可选参数：
  • selector：用于选择要截图元素的 CSS 选择器。
  • width：以像素为单位的宽度（默认为 800）。
  • height：以像素为单位的高度（默认为 600）。

puppeteer_click

点击页面上的某个元素。

• 必需参数：
  • selector：要点击的元素的 CSS 选择器。

puppeteer_fill

填写输入字段的内容。

• 必需参数：
  • selector：输入字段的 CSS 选择器。
  • value：要填写的值。

puppeteer_submit_form

提交表单。

• 必需参数：
  • selector：表单元素或其父容器的 CSS 选择器。

安全注意事项

1. 在生产环境中，确保服务器运行在安全的网络上，并配置适当的安全策略。
2. 避免将敏感信息明文存储在代码中，建议使用环境变量。
3. 定期更新依赖项以防止已知的安全漏洞。

日志记录

日志级别

• debug：调试模式，输出详细日志信息。
• info：默认模式，输出一般信息日志。
• warn：警告模式，输出潜在问题的日志。
• error：错误模式，输出严重错误的日志。

日志格式

{
  "timestamp": "2023-10-26T15:36:40.123Z",
  "level": "info",
  "message": "Server started on port 8080"
}

错误处理

常见错误

无法连接到浏览器实例

Error: Cannot connect to browser instance

解决方法：

• 确保 Chrome 浏览器正在运行。
• 检查远程调试端口是否正确配置。

页面未加载完成

Error: Page not loaded

解决方法：

• 确保目标 URL 可用。
• 增加等待时间或使用适当的页面加载事件监听。

高级功能

自定义浏览器配置

在启动时自定义浏览器选项：

{
  "executablePath": "/path/to/chrome",
  "args": ["--incognito"],
  "userDataDir": "/path/to/user/data"
}

扩展支持

通过加载扩展来增强浏览器功能：

"extensions": ["/path/to/extension.crx"]

开发指南

贡献代码

1. 创建一个分支用于你的更改。
2. 提交并推送你的更改。
3. 创建一个拉取请求以供审核。

问题报告

1. 打开 Issues 页面。
2. 描述问题的详细信息和复现步骤。

附录

命令行选项

# 启动服务器
npm start -- --port 8081

# 运行测试
npm test

# 打包项目
npm run build

FAQ

问：如何处理 CORS 问题？ 答：在配置中启用跨域资源共享：

"cors": {
  "enabled": true,
  "origin": "*"
}

问：如何捕获浏览器截图？ 答：使用 page.screenshot() 方法，并指定输出路径和格式。

联系方式

如需更多信息，请访问 项目主页 或联系 维护人员。

📄 许可证

本项目遵循 MIT 许可证。详情请查阅 LICENSE 文件。

👏 贡献者

感谢以下贡献者对项目的支持：

• 张三
• 李四
• 王五