configurable puppeteer

在AI辅助开发日益普及的今天，我们经常需要让AI助手能够“看见”和操作真实的网页。无论是抓取动态内容、自动截图、还是执行复杂的UI测试，一个强大的浏览器自动化工具都是不可或缺的。mcp-configurable-puppeteer正是为此而生，它作为一个模型上下文协议服务器，将Puppeteer这一成熟的浏览器自动化库带入了AI代理的工作流。更重要的是，它通过环境变量提供了灵活的配置能力，让你能够轻松定制浏览器行为，而无需修改一行服务器代码。

项目基本信息

一、项目介绍

mcp-configurable-puppeteer是一个专注且实用的MCP服务器，它扮演着AI助手与真实浏览器之间的桥梁。通过将Puppeteer的自动化能力封装为标准MCP工具，它赋予了LLM与网页进行交互的能力。

核心工具集

该服务器提供了一套精简但全面的工具，覆盖了浏览器自动化的核心需求：

• 导航 (puppeteer_navigate): 控制浏览器导航到指定的URL。
• 截图 (puppeteer_screenshot): 捕获整个页面或特定元素的截图。
• 交互 (puppeteer_click, puppeteer_hover, puppeteer_fill, puppeteer_select): 模拟真实的用户操作，包括点击、悬停、填写表单和选择下拉菜单。
• 脚本执行 (puppeteer_evaluate): 在浏览器上下文中直接执行JavaScript代码，实现更复杂的操作或数据提取。

此外，它还通过MCP资源接口暴露了浏览器控制台日志和截图文件，方便AI助手在执行任务后进行调试和结果查阅。

“可配置”的亮点

正如其名，项目最大的特色在于其可配置性。它允许用户通过 PUPPETEER_ARGS 环境变量，以JSON字符串的形式传递任何Puppeteer启动选项。这意味着你可以自由地切换浏览器类型（如Firefox）、设置视口大小、配置代理，甚至启用无头模式，而这一切都无需修改服务器源码。

二、核心优势

高度灵活的浏览器定制

通过PUPPETEER_ARGS环境变量，你可以将Puppeteer的任何启动参数应用到该MCP服务器。这为不同场景下的自动化任务打开了方便之门。例如，你可以轻松切换到Firefox进行跨浏览器测试，或者设置特定的视口尺寸来模拟移动设备。

极简的部署方式

项目设计之初就考虑了使用的便捷性。通过npx，你无需手动克隆、安装依赖或编译，只需在MCP客户端配置中添加几行代码，npx会自动从GitHub拉取并运行最新的服务器代码。这极大地降低了用户的使用门槛。

专注核心功能

与一些功能庞杂的浏览器MCP工具不同，mcp-configurable-puppeteer保持了一组经过精心挑选的核心工具。它没有试图复现Puppeteer的全部API，而是聚焦于最通用的导航、交互、截图和脚本执行，这使得其工具列表简洁易懂，AI也能更准确地选择和调用。

开放与标准的协议

项目遵循MCP标准和MIT开源协议。这意味着它不仅能在Claude Desktop等主流MCP客户端中无缝集成，也为开发者进行二次开发和商业集成提供了法律上的便利。

三、适用场景

AI驱动的Web自动化测试

你可以让AI助手通过自然语言指令执行测试流程。例如：“打开https://example.com/login，在用户名和密码框填入testuser和pass123，点击登录按钮，然后截图保存为after_login.png”。

动态网页数据抓取与监控

对于依赖JavaScript渲染的网站，传统的HTTP请求库无能为力。你可以指挥AI：“导航到某新闻网站，等待3秒让动态内容加载，然后执行JavaScript脚本，提取首页所有新闻标题和链接，并以JSON格式返回。”

前端开发辅助与视觉回归测试

开发人员可以在编码过程中，随时让AI助手检查页面表现。例如：“在当前开发服务器http://localhost:3000的页面上，点击‘提交’按钮，然后把控制台里的报错信息给我”，或者“对http://localhost:3000/dashboard进行截图，并命名为baseline.png”。

自动化的网页表单填写

对于需要频繁填写的线上表单（如活动报名、信息提交），可以预先设定指令，让AI助手自动完成填写和提交过程。

四、安装教程

mcp-configurable-puppeteer的安装极为简单，主要通过配置你的MCP客户端来完成。

环境要求

通用配置步骤

在你的MCP客户端配置文件（以Claude Desktop为例，通常位于~/Library/Application Support/Claude/claude_desktop_config.json）中，添加以下配置块。

1. 基础配置（使用默认Chrome）

{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": ["-y", "github:afshawnlotfi/mcp-configurable-puppeteer"]
    }
  }
}

2. 进阶配置（使用环境变量自定义）
如果你想使用Firefox浏览器，可以像下面这样配置：

{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": ["-y", "github:afshawnlotfi/mcp-configurable-puppeteer"],
      "env": {
        "PUPPETEER_ARGS": "{\"browser\": \"firefox\"}"
      }
    }
  }
}

保存配置文件后，完全退出并重启你的MCP客户端。首次运行时，npx会自动下载服务器代码及Puppeteer所需的浏览器驱动，请耐心等待片刻。

五、使用示例

以下是几个在Claude Desktop中与mcp-configurable-puppeteer交互的典型对话示例。

示例一：导航与截图

用户: 使用puppeteer，导航到 https://example.com，然后给整个页面截个图，命名为 example-homepage。

AI的操作:
AI会依次调用puppeteer_navigate和puppeteer_screenshot工具，完成指令后，截图文件将保存在服务器的工作目录中。

示例二：表单填写与提交

用户: 用puppeteer打开 https://httpbin.org/forms/post，在 custname 字段填 "张三"， custtel 填 "13800138000"，然后点击提交按钮。

AI的操作:
AI会导航到目标URL，然后调用puppeteer_fill填写指定字段，最后调用puppeteer_click点击提交按钮。

示例三：执行自定义JavaScript

用户: 用puppeteer打开 https://news.ycombinator.com，然后执行一段JavaScript，告诉我页面上有多少个链接（<a>标签）。

AI的操作:
AI会先调用puppeteer_navigate，然后调用puppeteer_evaluate，并传入如下脚本：

document.querySelectorAll('a').length;

AI会得到脚本的返回值，并回复你：“页面共有 XXX 个链接。”

六、常见问题

问：配置后，AI提示“工具未找到”或“服务器未连接”？

答：请按以下步骤排查：

1. 确认配置正确：检查JSON格式是否正确，特别是env中的PUPPETEER_ARGS的值必须是合法的JSON字符串，注意引号和斜杠的转义。
2. 检查网络：npx首次运行时需要从GitHub下载代码，请确保网络连接通畅。
3. 查看客户端日志：大多数MCP客户端都有查看扩展/插件日志的功能，那里通常会包含服务器的启动错误信息，是排查问题的关键。

问：如何查看我保存的截图或控制台日志？

答：这些被暴露为MCP资源。你可以直接向AI提问，例如：“把刚才命名为example-homepage的截图给我”，或“查看浏览器的控制台日志”。AI会通过access_mcp_resource工具来获取这些内容。

问：PUPPETEER_ARGS 可以设置哪些参数？

答：任何Puppeteer puppeteer.launch() 方法接受的参数都可以设置。常用参数包括：

• headless (boolean): 是否使用无头模式（不显示浏览器界面）。
• defaultViewport (object): 设置视口宽高，如 {"width":1280, "height":800}。
• args (array): 传递给浏览器的命令行参数。
• executablePath (string): 指定浏览器可执行文件的路径。

你可以查阅Puppeteer官方文档获取完整的参数列表。

七、总结

mcp-configurable-puppeteer是一个小巧、专注且高度灵活的MCP服务器。它没有复杂的功能堆砌，而是聚焦于通过可配置的方式，将Puppeteer的核心自动化能力以最简捷的形态交付给AI助手。其基于npx的极简部署方式和通过环境变量进行配置的巧思，充分体现了“约定大于配置”和“灵活定制”的平衡。

对于需要让AI进行网页交互、截图或数据抓取的开发者和自动化爱好者来说，这是一个值得加入工具箱的实用组件。它证明了，一个好的MCP工具不一定需要大而全，精准地解决一个核心痛点，并留出足够的定制空间，往往更能赢得用户的青睐。