Puppeteer MCP Server

Puppeteer MCP Server

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

致谢

本项目是一项实验性实现，灵感来自 @modelcontextprotocol/server-puppeteer。虽然目标和理念相似，但它通过 Model Context Protocol 探索了浏览器自动化的其他实现方式。

功能

• 浏览网页
• 截取屏幕截图
• 点击元素
• 填写表单
• 选择选项
• 悬停在元素上
• 执行 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

3. 构建项目：

npm run build

4. 运行服务：

npm start

MCP 服务配置

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

适用于 Claude Desktop App

将以下内容添加到 Claude Desktop 配置文件中（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", // Optional: specific tab URL
     "debugPort": 9222 // Optional: defaults to 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 文件。