Puppeteer MCP 服务器

这是一个通过 Puppeteer 提供浏览器自动化能力的 Model Context Protocol (MCP) 服务器，并具备智能浏览器管理功能。此服务器使AI助手能够控制 Chromium 浏览器，抓取屏幕截图，提取内容并与网页进行交互。

✨ 此实现与其他实现的关键区别在于它能够访问页面的原始DOM内容和控制台！

MCP 客户端配置

在您的 MCP 客户端配置中添加以下内容：

{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": [
        "-y",
        "@ratiofu/mcp-puppeteer"
      ]
    }
  }
}

注意事项：

• 某些 MCP 客户端支持额外的服务器配置选项。查阅您的 MCP 客户端文档以获取高级配置设置。
• 如果您正在使用其他基于 Puppeteer 的 MCP 服务器，请考虑使用一个独特的名称如 "puppeteer-ratiofu" 来避免冲突。一次只运行一个 Puppeteer MCP 服务器，并在更改服务器名称时相应地更新任何本地代理指导。

可用工具

• navigate: 导航到 URL
• list_tab_urls: 列出所有打开标签页的 URL
• click: 使用 CSS 选择器点击元素
• take_screenshot: 捕获页面截图
• get_html: 提取页面 HTML 内容
• get_console: 获取浏览器控制台输出

前提条件

您需要运行带有远程调试功能启用的 Chromium：

macOS

open -a "Chromium" --args --remote-debugging-port=9222

Linux

chromium --remote-debugging-port=9222

Windows

chromium --remote-debugging-port=9222

工作原理

当您的 MCP 客户端需要时，服务器会自动下载并通过 npx 运行。无需手动安装！它使用 Chromium 的远程调试协议来控制您的浏览器。

故障排除

Chromium 连接问题

错误：“无法连接到 Chromium”

确保您确实启动了 Chromium（参见上述步骤）。

您可以通过在浏览器中打开 http://localhost:9222/json 来验证 Chromium 是否已准备好。

MCP 客户端问题

服务器未响应：

1. 确保 Chromium 正在运行并启用了调试端口（参见前提条件部分）
2. 检查您的 MCP 客户端配置是否与示例匹配
3. 验证已安装 Node.js 22+ (node --version)

需要手动测试？

echo '{}' | npx @ratiofu/mcp-puppeteer

开发

对于本地开发：

git clone https://github.com/ratiofu/mcp-puppeteer
cd mcp-puppeteer
pnpm install
pnpm run build
pnpm start

开发脚本

pnpm run dev            # 自动重建和重启
pnpm run test           # 运行单元测试
pnpm run test:coverage  # 运行带有覆盖率的测试
pnpm run quality        # 全面的质量管道（类型检查 + 代码检查 + 测试覆盖率）
pnpm run lint           # 使用 Biome 检查代码
pnpm run lint:fix       # 自动修复代码检查和格式化问题
pnpm run inspector      # 使用 MCP Inspector 测试

架构

• 管道传输：直接通过标准输入/输出与 MCP 客户端通信
• Puppeteer 核心：不带捆绑浏览器的浏览器自动化
• 自动清理：进程退出时清理浏览器资源