Puppeteer MCP 服务器

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

致谢

本项目是一个实验性实现，灵感来源于 @modelcontextprotocol/server-puppeteer。虽然它具有相似的目标和概念，但它探索了通过模型上下文协议进行浏览器自动化的替代方法。

<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        # 文档

安装

选项 1：从 npm 安装

npm install -g puppeteer-mcp-server

您也可以使用 npx 直接运行它，无需安装：

npx puppeteer-mcp-server

选项 2：从源代码安装

1. 克隆此存储库或下载源代码
2. 安装依赖项：

npm install

3. 构建项目：

npm run build

4. 运行服务器：

npm start

MCP 服务器配置

要将此工具与 Claude 一起使用，您需要将其添加到您的 MCP 设置配置文件中。

对于 Claude 桌面应用程序

将以下内容添加到您的 Claude 桌面配置文件（位于 Windows 上的 %APPDATA%\Claude\claude_desktop_config.json 或 macOS 上的 ~/Library/Application Support/Claude/claude_desktop_config.json）：

如果通过 npm 全局安装：

{
  "mcpServers": {
    "puppeteer": {
      "command": "puppeteer-mcp-server",
      "args": [],
      "env": {}
    }
  }
}

使用 npx（无需安装）：

{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": ["-y", "puppeteer-mcp-server"],
      "env": {}
    }
  }
}

如果从源代码安装：

{
  "mcpServers": {
    "puppeteer": {
      "command": "node",
      "args": ["path/to/puppeteer-mcp-server/dist/index.js"],
      "env": {
        "NODE_OPTIONS": "--experimental-modules"
      }
    }
  }
}

对于 Claude VSCode 扩展

将以下内容添加到您的 Claude VSCode 扩展 MCP 设置文件（位于 Windows 上的 %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json 或 macOS 上的 ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json）：

如果通过 npm 全局安装：

{
  "mcpServers": {
    "puppeteer": {
      "command": "puppeteer-mcp-server",
      "args": [],
      "env": {}
    }
  }
}

使用 npx（无需安装）：

{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": ["-y", "puppeteer-mcp-server"],
      "env": {}
    }
  }
}

如果从源代码安装：

{
  "mcpServers": {
    "puppeteer": {
      "command": "node",
      "args": ["path/to/puppeteer-mcp-server/dist/index.js"],
      "env": {
        "NODE_OPTIONS": "--experimental-modules"
      }
    }
  }
}

对于源代码安装，请将 path/to/puppeteer-mcp-server 替换为您安装此工具的实际路径。

用法

标准模式

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

活动标签页模式

要连接到现有的 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 执行错误
• 屏幕截图失败

每个工具调用返回：

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

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

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

贡献

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

许可证

此项目已获得 MIT 许可证的许可 - 有关详细信息，请参阅 LICENSE 文件。