Puppeteer MCP 服务器

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

致谢

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

特征

浏览网页
截取屏幕截图
点击元素
填写表格
选择选项
悬停元素
执行 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：从源安装

克隆此存储库或下载源代码
安装依赖项：

npm install

构建项目：

npm run build

运行服务器：

npm start

MCP 服务器配置

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

对于克劳德桌面应用程序

将以下内容添加到您的 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 窗口：

完全关闭所有现有的 Chrome 实例
启动启用远程调试的 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
在 Chrome 中导航到您想要的网页
使用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 - 选择元素的 CSS 选择器
- value - 要选择的选项值

puppeteer_hover

将鼠标悬停在元素上。

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

puppeteer_evaluate

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

必需： script - 要执行的 JavaScript 代码

安全注意事项

使用远程调试时：

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

日志记录和调试

基于文件的日志记录

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

位置： logs/目录
文件模式： mcp-puppeteer-YYYY-MM-DD.log
日志旋转：
- 每日轮换
- 最大尺寸：每个文件 20MB
- 保留：14天
- 自动压缩旧日志

日志级别

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

记录的信息

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

错误处理

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

连接失败
缺失元素
无效的选择器
JavaScript 执行错误
截图失败

每次工具调用都会返回：

成功/失败状态
如果失败则显示详细的错误信息
操作成功时的结果数据

所有错误也会记录到日志文件中：

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

贡献

欢迎贡献！请阅读我们的贡献指南，了解如何提交拉取请求、报告问题以及为项目做出贡献。

执照

该项目根据 MIT 许可证获得许可 - 有关详细信息，请参阅LICENSE文件。

You must be authenticated.

security – no known vulnerabilities

license - permissive license

quality - confirmed to work

local-only server

The server can only run on the client's local machine because it depends on local resources.

Tools

通过 Puppeteer 实现浏览器自动化，支持导航、表单交互以及与活动的 Chrome 实例的连接，以实现全面的网页交互。

Related Resources

Reddit Discussion about this server

Related MCP Servers

Puppeteer MCP Server
jwaldor
A
security
F
license
A
quality
Enables LLMs to perform web browsing tasks, take screenshots, and execute JavaScript using Puppeteer for browser automation.
Last updated -
4
15,502
1
JavaScript
Steel Puppeteer
rdvo
-
security
A
license
-
quality
A Model Context Protocol server that enables LLMs to automate web browsers using Puppeteer, allowing navigation, screenshots, form filling, and JavaScript execution in a real browser environment.
Last updated -
JavaScript
MIT License
MCP Operator
willer
-
security
F
license
-
quality
A web browser automation server that allows AI assistants to control Chrome with persistent state management, enabling complex browsing tasks through asynchronous browser operations.
Last updated -
1
Python
Configurable Puppeteer MCP Server
afshawnlotfi
-
security
F
license
-
quality
A Model Context Protocol server that provides browser automation capabilities using Puppeteer with configurable options through environment variables, enabling LLMs to interact with web pages, take screenshots, and execute JavaScript in a browser environment.
Last updated -
1
JavaScript

View all related MCP servers