A simple MCP Server for controlling Chrome via Puppeteer

Puppeteer MCP Server

一个通过 Puppeteer 提供浏览器自动化功能并具备智能浏览器管理能力的模型上下文协议（MCP）服务。此服务支持 AI 助手控制 Chromium 浏览器、截取屏幕截图、提取内容并与网页交互。

✨ 与其他实现的主要区别在于，此实现支持访问页面原始 DOM 内容和控制台！

MCP 客户端配置

将以下内容添加到 MCP 客户端配置中：

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

注意：

• 某些 MCP 客户端支持其他服务配置选项。请查阅 MCP 客户端文档，了解高级配置设置。
• 如果你正在使用其他基于 Puppeteer 的 MCP 服务，可考虑使用 "puppeteer-ratiofu" 这样的唯一名称以避免冲突。一次只运行一个 Puppeteer MCP 服务；如果更改了服务名称，请相应更新任何本地 Agent 指引。

可用工具

• 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            # Auto-rebuild and restart
pnpm run test           # Run unit tests
pnpm run test:coverage  # Run tests with coverage
pnpm run quality        # Full quality pipeline (typecheck + lint + test coverage)
pnpm run lint           # Check code with Biome linter
pnpm run lint:fix       # Auto-fix linting and formatting issues
pnpm run inspector      # Test with MCP Inspector

架构

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