AI导哈

浏览器自动化管理服务

Puppeteer Swarm MCP是一个基于Puppeteer的浏览器自动化管理服务，支持标签池管理、自动恢复和空闲释放，适用于大规模网页爬取和自动化测试场景。

  • by greatSumini
  • TypeScript
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 greatSumini/puppeteer-swarm-mcp

使用说明

Puppeter Swarm MCP

用于浏览器自动化的MCP服务器 选项卡池 支持使用Puppeteer。

特性

  • 显式浏览器控件：通过按需启动和关闭浏览器 launch/close 工具
  • 选项卡池：同时管理多个浏览器选项卡
  • 自动释放：空闲超时后自动释放标签页（默认值：5分钟）
  • 自动恢复：自动恢复崩溃的选项卡
  • 可配置的：通过CLI参数设置选项卡计数和无头模式

安装

选项1：从npm安装

npm install -g puppeteer-swarm-mcp

或者直接使用npx运行：

npx puppeteer-swarm-mcp

选项2：从源代码安装

git clone https://github.com/greatSumini/puppeteer-swarm-mcp.git
cd puppeteer-swarm-mcp
npm install
npm run build

用法

# Default: 5 tabs, headless=false
puppeteer-swarm-mcp

# Custom tab count
puppeteer-swarm-mcp --tabs=10

# Headless mode
puppeteer-swarm-mcp --headless

# Combined options
puppeteer-swarm-mcp --tabs=10 --headless

环境变量

TAB_COUNT=10 HEADLESS=true puppeteer-swarm-mcp

MCP客户端集成

Puppeter Swarm MCP可以与支持模型上下文协议（MCP）的各种AI编码助手和IDE集成。

需求

  • Node.js>=v18.0.0
  • 兼容MCP的客户端（Claude Code、Cursor、VS Code、Windsurf等）
Install in Claude Code

运行此命令：

claude mcp add puppeteer-swarm -- npx -y puppeteer-swarm-mcp --tabs=5 --headless

或者使用自定义选项：

claude mcp add puppeteer-swarm -- npx -y puppeteer-swarm-mcp --tabs=10
Install in Cursor

首选 Settings -> Cursor Settings -> MCP -> Add new global MCP server

将以下配置添加到您的 ~/.cursor/mcp.json 文件：

{
  "mcpServers": {
    "puppeteer-swarm": {
      "command": "npx",
      "args": ["-y", "puppeteer-swarm-mcp", "--tabs=5", "--headless"]
    }
  }
}
Install in Claude Desktop

将以下内容添加到您的Claude Desktop配置文件中：

  • macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
  • 窗户： %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "puppeteer-swarm": {
      "command": "npx",
      "args": ["-y", "puppeteer-swarm-mcp", "--tabs=5", "--headless"]
    }
  }
}
Install in VS Code

将此添加到您的VS Code MCP配置文件中。看 VS代码MCP文档 了解更多信息。

"mcp": {
  "servers": {
    "puppeteer-swarm": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "puppeteer-swarm-mcp", "--tabs=5", "--headless"]
    }
  }
}
Install in Windsurf

将此添加到您的Windsurf MCP配置文件中：

{
  "mcpServers": {
    "puppeteer-swarm": {
      "command": "npx",
      "args": ["-y", "puppeteer-swarm-mcp", "--tabs=5", "--headless"]
    }
  }
}
Install in Cline
  1. 打开 克莱恩
  2. 点击汉堡菜单图标（☰）进入 MCP服务器 章节
  3. 选择 远程服务器 标签
  4. 点击 编辑配置 按钮
  5. 添加木偶师群 mcpServers:
{
  "mcpServers": {
    "puppeteer-swarm": {
      "command": "npx",
      "args": ["-y", "puppeteer-swarm-mcp", "--tabs=5", "--headless"]
    }
  }
}
Install in Zed

将此添加到您的Zed settings.json:

{
  "context_servers": {
    "puppeteer-swarm": {
      "source": "custom",
      "command": "npx",
      "args": ["-y", "puppeteer-swarm-mcp", "--tabs=5", "--headless"]
    }
  }
}

可用工具

发射

初始化浏览器和选项卡池。 必须在使用任何其他浏览器工具之前调用。

参数：无

退货:

{
  "message": "브라우저가 성공적으로 시작되었습니다.",
  "config": {
    "tabCount": 5,
    "headless": false,
    "idleTimeout": 300000
  }
}

关闭

关闭浏览器和所有选项卡。

参数：无

退货:

{
  "message": "브라우저가 종료되었습니다."
}

get_tool_status

获取选项卡池的当前状态。之前可以打电话 launch 检查初始化状态。

参数：无

退货 （发射后）：

{
  "initialized": true,
  "total": 5,
  "idle": 3,
  "busy": 2
}

退货 （发射前）：

{
  "initialized": false,
  "message": "브라우저가 초기화되지 않았습니다. 먼저 'launch' 도구를 호출하세요."
}

导航

分配一个空闲选项卡并导航到URL。

参数:

名称 类型 必填 描述
url string 是 要导航到的URL
waitUntil string 否 等待条件(load, domcontentloaded, networkidle0, networkidle2)

退货:

{
  "tabId": "tab-1",
  "url": "https://example.com",
  "title": "Example Domain"
}

get_content

从页面中提取HTML或文本内容。

参数:

名称 类型 必填 描述
tabId string 是 目标选项卡ID
type string 否 提取格式(html, text).违约： text

退货:

{
  "content": "..."
}

截图

捕获页面截图。

参数:

名称 类型 必填 描述
tabId string 是 目标选项卡ID
fullPage boolean 否 捕获整页。违约： false

退货：图像内容（base64 PNG）

点击

通过CSS选择器单击元素。

参数:

名称 类型 必填 描述
tabId string 是 目标选项卡ID
selector string 是 CSS选择器

退货:

{
  "success": true
}

类型

在输入框中键入文本。

参数:

名称 类型 必填 描述
tabId string 是 目标选项卡ID
selector string 是 CSS选择器
text string 是 要键入的文本

退货:

{
  "success": true
}

评估

在页面上下文中执行JavaScript。

参数:

名称 类型 必填 描述
tabId string 是 目标选项卡ID
script string 是 要执行的JavaScript代码

退货:

{
  "result": "..."
}

wait_for_selector

等待元素出现在DOM中。

参数:

名称 类型 必填 描述
tabId string 是 目标选项卡ID
selector string 是 CSS选择器
timeout number No 超时（毫秒）。默认值： 30000

退货:

{
  "success": true
}

release_tab

释放一个标签回到空闲状态。

参数:

名称 类型 必填 描述
tabId string 是 要释放的选项卡ID

退货:

{
  "success": true
}

工作流示例

1. launch()
   -> Initialize browser and tab pool

2. navigate({ url: "https://example.com" })
   -> Returns { tabId: "tab-1", ... }

3. get_content({ tabId: "tab-1", type: "text" })
   -> Returns page content

4. click({ tabId: "tab-1", selector: "button.submit" })
   -> Click a button

5. release_tab({ tabId: "tab-1" })
   -> Release the tab for reuse

6. close()
   -> Close browser when done (optional)

备注：浏览器不会自动启动。你必须打电话 launch 在使用任何浏览器工具之前。

日志记录

日志存储在 logs/ 目录：

  • 文件模式： mcp-puppeteer-YYYY-MM-DD.log
  • 每日轮换，每个文件最大20MB
  • 自动压缩功能可保留14天

许可证

MIT许可证-请参阅 许可证 文件以获取详细信息。

作者

崔素民 - GitHub

相关 MCP