STARWARCLOUD STARWAR.AI
返回市场
Puppeteer-MCP-服务器

Puppeteer-MCP-服务器

作者：merajmehrabi243 星标更新：2025-03-14
安装使用来源：spider==github.com

项目介绍

Puppeteer MCP 服务器

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

致谢

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

<a href="https://glama.ai/mcp/servers/lpt1tvbubf"><img width="380" height="200" src="https://gips3.baidu.com/it/u=605663264,3185482604&fm=3081&app=3081&f=PNG?w=760&h=400" alt="Puppeteer Server MCP 服务器" /></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
  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 文件。