AI导哈

浏览器自动化服务器

一个基于Puppeteer的浏览器自动化服务器，提供网页导航、截图、表单填写等功能，支持连接现有Chrome窗口。

  • by merajmehrabi
  • TypeScript
  • 本地部署
  • 243 星标
  • 更新于
在 GitHub 查看 merajmehrabi/puppeteer-mcp-server

使用说明

木偶MCP服务器

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

致谢

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

特性

  • 浏览网页
  • 截图
  • 点击元素
  • 填写表格
  • 选择选项
  • 悬停元素
  • 执行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 Desktop配置文件（位于 %APPDATA%\Claude\claude_desktop_config.json 在Windows或 ~/Library/Application Support/Claude/claude_desktop_config.json 在 macOS 上：

如果通过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设置文件（位于 %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json 在Windows或 ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json 在 macOS 上：

如果通过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_navigation

导航到URL。

  • 必修的： url -要导航到的URL

木偶戏

截取当前页面或特定元素的屏幕截图。

  • 必修的： name -屏幕截图的名称
  • 可选：
    • selector -用于截图元素的CSS选择器
    • width -宽度（像素）（默认值：800）
    • height -高度（像素）（默认值：600）

木偶戏

单击页面上的元素。

  • 必修的： selector -用于单击元素的CSS选择器

木偶戏

填写输入字段。

  • 必修的：
    • selector -输入字段的CSS选择器
    • value -要输入的文本

木偶师_选择

使用下拉菜单。

  • 必修的：
    • selector -用于选择元素的CSS选择器
    • value -要选择的选项值

木偶戏

将鼠标悬停在元素上。

  • 必修的： selector -用于悬停元素的CSS选择器

木偶师_评价

在浏览器控制台中执行JavaScript。

  • 必修的： script -要执行的JavaScript代码

安全考虑

使用远程调试时：

  • 仅在受信任的网络上启用
  • 使用唯一的调试端口
  • 不使用时关闭调试端口
  • 切勿将调试端口暴露给公共网络

日志记录和调试

基于文件的日志记录

服务器使用Winston实现了全面的日志记录：

  • 地点： logs/ 目录
  • 文件模式： mcp-puppeteer-YYYY-MM-DD.log
  • 日志轮换：
    • 每日轮换
    • 最大大小：每个文件20MB
    • 保留期：14天
    • 自动压缩旧日志

日志级别

  • 调试：详细的调试信息
  • 信息：一般操作信息
  • 警告：警告信息
  • 错误：错误事件和异常

记录的信息

  • 服务器启动/关闭事件
  • 浏览器操作（启动、连接、关闭）
  • 导航尝试和结果
  • 工具执行和结果
  • 带有堆栈跟踪的错误详细信息
  • 浏览器控制台输出
  • 资源使用情况（屏幕截图、控制台日志）

错误处理

服务器为以下对象提供详细的错误消息：

  • 连接失败
  • 缺少元素
  • 选择器无效
  • JavaScript执行错误
  • 屏幕截图故障

每次工具调用返回：

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

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

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

贡献

欢迎投稿！请阅读我们的 贡献指南 有关如何提交pull请求、报告问题和为项目做出贡献的详细信息。

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

相关 MCP