Puppeteer MCP服务器

你是否曾经希望自己的AI助手能够像真人一样操作浏览器：点击按钮、填写表单、执行JavaScript，甚至捕获控制台日志？今天要介绍的开源项目Puppeteer MCP服务器，正是为了实现这个目标而设计的。它是一个基于Puppeteer的MCP服务器，让大型语言模型能够通过简单的工具调用，完成复杂的浏览器自动化任务。

项目基本信息

一、项目介绍

Puppeteer MCP服务器是模型上下文协议官方提供的服务器之一，它封装了Puppeteer这个强大的浏览器自动化库。通过这个服务器，AI助手可以获得以下能力：

• 导航到任意URL
• 截取网页截图（全页面或特定元素）
• 点击、悬停、填写表单、下拉选择
• 在浏览器控制台中执行JavaScript
• 访问浏览器控制台日志
• 管理截图资源

这个服务器的一个显著特点是高度可定制。你可以通过环境变量或工具调用参数，灵活配置Puppeteer的启动选项，包括是否使用无头模式、指定Chrome可执行文件路径、设置视口大小等。这为高级用户提供了极大的灵活性。

安全提醒：由于该服务器在您的机器上运行浏览器，因此它可以访问本地文件和本地/内部IP地址。使用此MCP服务器时请谨慎操作，确保不会暴露任何敏感数据。

二、核心优势

官方出品，稳定可靠

这是MCP官方团队维护的服务器，代码质量有保证，会跟随MCP协议版本同步更新。

功能全面

提供了7个浏览器自动化工具，覆盖了网页交互的主要场景：

• 导航
• 截图
• 点击
• 悬停
• 填写表单
• 下拉选择
• 执行JavaScript

可定制的启动选项

这是区别于其他Puppeteer MCP的重要特性。你可以：

• 通过环境变量PUPPETEER_LAUNCH_OPTIONS全局配置
• 通过puppeteer_navigate工具的launchOptions参数动态配置
• 设置allowDangerous标志来使用一些高风险但有用的参数（如--no-sandbox、--disable-web-security）

资源访问

除了工具调用，服务器还提供两种资源的访问：

• 控制台日志：以文本格式访问浏览器中的所有控制台输出
• 屏幕截图：通过名称访问捕获的PNG图像（支持base64编码输出）

多种部署方式

支持Docker和NPX两种运行方式：

• Docker方式：使用无头Chromium，适合服务器部署
• NPX方式：会打开可见的浏览器窗口，适合本地调试

三、适用场景

开发者学习和参考

对于想学习浏览器自动化或MCP服务器开发的开发者，这是一个很好的学习范例。它展示了如何将Puppeteer封装成标准的MCP工具。

网页自动化测试

可以用它来构建自动化测试脚本。例如，让AI自动登录系统、填写表单、验证页面元素，并捕获测试过程中的截图和控制台日志。

数据抓取

对于需要JavaScript渲染的动态网站，传统的HTTP请求无法获取完整内容。通过这个服务器，AI可以驱动真实浏览器，执行页面脚本，获取渲染后的内容。

日常工作和效率提升

与Claude Desktop等客户端结合后，你可以用自然语言指挥AI完成浏览器操作：

• “帮我打开这个网站并截取首页截图”
• “点击页面上的‘登录’按钮，然后填写用户名和密码”
• “在控制台执行这段JavaScript，并返回结果”

四、安装教程

系统要求

安装步骤

Puppeteer MCP服务器的安装非常简单，不需要克隆代码仓库，直接通过NPX或Docker即可运行。

方式一：NPX安装（推荐用于本地开发）

这种方式会在你的机器上直接运行Puppeteer，并且会打开可见的浏览器窗口，便于观察自动化过程。

对于Claude Desktop：

找到Claude Desktop的配置文件：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

添加以下配置：

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

对于VS Code：

打开VS Code的用户设置（JSON）文件（Ctrl+Shift+P -> “Preferences: Open User Settings (JSON)”），添加：

{
  "mcp": {
    "servers": {
      "puppeteer": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-puppeteer"]
      }
    }
  }
}

方式二：Docker安装（推荐用于服务器部署）

这种方式在Docker容器中运行，使用无头Chromium，适合生产环境或远程服务器。

在Claude Desktop配置文件中添加：

{
  "mcpServers": {
    "puppeteer": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "--init", "-e", "DOCKER_CONTAINER=true", "mcp/puppeteer"]
    }
  }
}

验证安装

配置完成后，重启客户端。在Claude Desktop中尝试输入：“使用puppeteer导航到https://example.com”。如果服务器正常工作，Claude会调用puppeteer_navigate工具，并返回导航结果。

五、使用示例

配置完成后，你就可以在MCP客户端中使用自然语言来调用各种浏览器自动化工具了。

示例1：导航到网页

用户指令：“使用puppeteer打开https://github.com”

AI会调用puppeteer_navigate工具，参数为{"url": "https://github.com"}。

示例2：截图

用户指令：“截取当前页面的全屏截图，命名为homepage”

AI会调用puppeteer_screenshot工具：

{
  "name": "homepage",
  "width": 1200,
  "height": 800
}

以base64格式返回截图：

{
  "name": "homepage",
  "encoded": true
}

示例3：点击和填写表单

假设你想让AI自动登录一个网站：

用户指令：

1. “导航到https://example.com/login”
2. “在#username输入框中填写‘myuser’”
3. “在#password输入框中填写‘mypass’”
4. “点击#submit按钮”

AI会依次调用：

• puppeteer_navigate
• puppeteer_fill (selector="#username", value="myuser")
• puppeteer_fill (selector="#password", value="mypass")
• puppeteer_click (selector="#submit")

示例4：自定义启动选项

用户指令：“打开https://example.com，使用非无头模式，并指定视口大小为1920x1080”

AI会调用：

{
  "url": "https://example.com",
  "launchOptions": {
    "headless": false,
    "defaultViewport": { "width": 1920, "height": 1080 }
  }
}

示例5：使用危险参数（需谨慎）

如果你需要绕过跨域限制进行测试，可以使用allowDangerous参数：

{
  "url": "https://example.com",
  "launchOptions": {
    "args": ["--disable-web-security"]
  },
  "allowDangerous": true
}

示例6：通过环境变量全局配置

在MCP配置中设置PUPPETEER_LAUNCH_OPTIONS：

{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-puppeteer"],
      "env": {
        "PUPPETEER_LAUNCH_OPTIONS": "{ \"headless\": false, \"executablePath\": \"/usr/bin/google-chrome\" }",
        "ALLOW_DANGEROUS": "true"
      }
    }
  }
}

六、常见问题

问题1：NPX方式运行时，浏览器没有打开

解决方案：NPX方式默认会打开可见的浏览器窗口。如果没有打开，请检查：

• 你的系统是否安装了Chromium或Chrome
• 在launchOptions中明确设置"headless": false

问题2：Docker方式运行时，提示“Cannot connect to the Docker daemon”

解决方案：请确保Docker守护进程正在运行。在macOS或Windows上，启动Docker Desktop应用。在Linux上，运行sudo systemctl start docker。

问题3：如何指定使用本地Chrome而不是下载的Chromium？

解决方案：通过launchOptions或环境变量设置executablePath：

{
  "launchOptions": {
    "executablePath": "C:/Program Files/Google/Chrome/Application/chrome.exe"
  }
}

问题4：执行JavaScript时，如何获取返回值？

解决方案：puppeteer_evaluate工具会返回脚本的执行结果。对于复杂对象，会被JSON序列化。

问题5：安全警告中提到的“本地数据安全风险”具体指什么？

解决方案：由于浏览器可以访问本地文件系统（通过file://协议）和内部网络，恶意或不受信任的指令可能会导致敏感数据泄露。建议：

• 仅从可信的来源输入指令
• 避免使用allowDangerous: true，除非你明确知道风险
• 定期检查控制台日志，确保没有意外访问

七、总结

Puppeteer MCP服务器是MCP官方生态中的重要一员。它干净、专注、稳定，提供了浏览器自动化所需的核心功能。与其他第三方浏览器MCP相比，它的优势在于：

• 官方维护：与MCP协议同步更新，兼容性有保障
• 高度可定制：支持灵活的启动选项配置，适应不同场景
• 双部署模式：NPX适合本地开发，Docker适合服务器部署
• 安全机制：内置危险参数保护，防止意外暴露敏感数据

如果你需要一个稳定、可靠、由官方维护的浏览器自动化MCP服务器，Puppeteer MCP服务器是最直接的选择。 无论是用于自动化测试、数据抓取，还是构建AI驱动的网页交互应用，它都能提供坚实的基础。

安全提醒：再次强调，由于浏览器可以访问本地资源，使用时请务必谨慎，确保AI指令来自可信来源。