Puppeteer MCP 服务器

该MCP服务器通过Puppeteer提供浏览器自动化功能，支持与新浏览器实例及现有Chrome窗口的交互。

致谢

本项目是基于@modelcontextprotocol/server-puppeteer的实验性实现。虽然目标与概念相似，但它通过模型上下文协议探索了浏览器自动化的替代方法。

功能特性

• 网页导航
• 截图功能
• 元素点击
• 表单填写
• 选项选择
• 元素悬停
• 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 - 选择元素的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文件。