Puppeteer MCP 服务器

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

致谢

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

功能

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

项目结构

/
├── src/
│   ├── config/        # Configuration modules
│   ├── tools/         # Tool definitions and handlers
│   ├── browser/       # Browser connection management
│   ├── types/         # TypeScript type definitions
│   ├── resources/     # Resource handlers
│   └── server.ts      # Server initialization
├── index.ts          # Entry point
└── README.md        # Documentation

安装

选项 1：从 npm 安装

npm install -g puppeteer-mcp-server

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

npx puppeteer-mcp-server

选项 2：从源代码安装

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

npm install

1. 构建项目：

npm run build

1. 运行服务器：

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 - 选择元素的 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文件。