Puppeteer MCP 服务器

此 MCP 服务器通过 Puppeteer 提供浏览器自动化功能，允许与新的浏览器实例和现有的 Chrome 窗口进行交互。

<a href="https://glama.ai/mcp/servers/lpt1tvbubf"><img width="380" height="200" src="https://glama.ai/mcp/servers/lpt1tvbubf/badge" alt="Puppeteer Server MCP server" /></a>

功能特性

• 网页导航
• 屏幕截图
• 元素点击
• 表单填写
• 选项选择
• 元素悬停
• 执行 JavaScript
• 智能 Chrome 标签页管理：
  • 连接到活动的 Chrome 标签页
  • 保留现有的 Chrome 实例
  • 智能连接处理

项目结构

/
├── src/
│   ├── config/        # 配置模块
│   ├── tools/         # 工具定义和处理程序
│   ├── browser/       # 浏览器连接管理
│   ├── types/         # TypeScript 类型定义
│   ├── resources/     # 资源处理程序
│   └── server.ts      # 服务器初始化
├── index.ts          # 入口点
└── README.md        # 文档

使用方法

标准模式

服务器默认会启动一个新的浏览器实例。

活动标签页模式

要连接到现有的 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_select

使用下拉菜单。

• 必需：
  • selector - select 元素的 CSS 选择器
  • value - 要选择的选项值

puppeteer_hover

悬停在元素上。

• 必需：selector - 要悬停的元素的 CSS 选择器

puppeteer_evaluate

在浏览器控制台中执行 JavaScript。

• 必需：script - 要执行的 JavaScript 代码

安全注意事项

使用远程调试时：

• 仅在受信任的网络上启用
• 使用唯一的调试端口
• 不使用时关闭调试端口
• 永远不要将调试端口暴露给公共网络

日志记录和调试

基于文件的日志记录

服务器使用 Winston 实现了全面的日志记录：

• 位置：logs/ 目录
• 文件模式：mcp-puppeteer-YYYY-MM-DD.log
• 日志轮换：
  • 每日轮换
  • 最大大小：每个文件 20MB
  • 保留期：14 天
  • 自动压缩旧日志

日志级别

• DEBUG：详细的调试信息
• INFO：常规操作信息
• WARN：警告消息
• ERROR：错误事件和异常

记录的信息

• 服务器启动/关闭事件
• 浏览器操作（启动、连接、关闭）
• 导航尝试和结果
• 工具执行和结果
• 带有堆栈跟踪的错误详细信息
• 浏览器控制台输出
• 资源使用情况（屏幕截图、控制台日志）

错误处理

服务器提供详细的错误消息，用于：

• 连接失败
• 缺少元素
• 无效的选择器
• JavaScript 执行错误
• 屏幕截图失败

每个工具调用返回：

• 成功/失败状态
• 如果失败，则返回详细的错误消息
• 如果成功，则返回操作结果数据

所有错误也会记录到日志文件中，包含：

• 时间戳
• 错误消息
• 堆栈跟踪（如果可用）
• 上下文信息

贡献

欢迎贡献！ 请阅读我们的 贡献指南，了解如何提交 pull request、报告问题以及为项目做出贡献的详细信息。

许可证

该项目根据 MIT 许可证获得许可 - 有关详细信息，请参见 LICENSE 文件。