Puppeteer Swarm MCP
Provides browser automation capabilities with tab pool management, enabling navigation, content extraction, screenshots, element interaction (clicking, typing), JavaScript evaluation, and selector waiting across multiple concurrent browser tabs.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Puppeteer Swarm MCP take a screenshot of the homepage of example.com and save it"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Puppeteer Swarm MCP
MCP server for browser automation with tab pool support using Puppeteer.
Features
Explicit Browser Control: Launch and close browser on demand via
launch/closetoolsTab Pool: Manage multiple browser tabs concurrently
Auto-release: Automatically release tabs after idle timeout (default: 5 minutes)
Auto-recovery: Automatically recover crashed tabs
Configurable: Set tab count and headless mode via CLI arguments
Related MCP server: Puppeteer MCP Server
Installation
Option 1: Install from npm
npm install -g puppeteer-swarm-mcpOr run directly using npx:
npx puppeteer-swarm-mcpOption 2: Install from source
git clone https://github.com/greatSumini/puppeteer-swarm-mcp.git
cd puppeteer-swarm-mcp
npm install
npm run buildUsage
# 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 --headlessEnvironment Variables
TAB_COUNT=10 HEADLESS=true puppeteer-swarm-mcpMCP Client Integration
Puppeteer Swarm MCP can be integrated with various AI coding assistants and IDEs that support the Model Context Protocol (MCP).
Requirements
Node.js >= v18.0.0
An MCP-compatible client (Claude Code, Cursor, VS Code, Windsurf, etc.)
Run this command:
claude mcp add puppeteer-swarm -- npx -y puppeteer-swarm-mcp --tabs=5 --headlessOr with custom options:
claude mcp add puppeteer-swarm -- npx -y puppeteer-swarm-mcp --tabs=10Go to: Settings -> Cursor Settings -> MCP -> Add new global MCP server
Add the following configuration to your ~/.cursor/mcp.json file:
{
"mcpServers": {
"puppeteer-swarm": {
"command": "npx",
"args": ["-y", "puppeteer-swarm-mcp", "--tabs=5", "--headless"]
}
}
}Add the following to your Claude Desktop configuration file:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"puppeteer-swarm": {
"command": "npx",
"args": ["-y", "puppeteer-swarm-mcp", "--tabs=5", "--headless"]
}
}
}Add this to your VS Code MCP config file. See VS Code MCP docs for more info.
"mcp": {
"servers": {
"puppeteer-swarm": {
"type": "stdio",
"command": "npx",
"args": ["-y", "puppeteer-swarm-mcp", "--tabs=5", "--headless"]
}
}
}Add this to your Windsurf MCP config file:
{
"mcpServers": {
"puppeteer-swarm": {
"command": "npx",
"args": ["-y", "puppeteer-swarm-mcp", "--tabs=5", "--headless"]
}
}
}Open Cline
Click the hamburger menu icon (☰) to enter the MCP Servers section
Choose Remote Servers tab
Click the Edit Configuration button
Add puppeteer-swarm to
mcpServers:
{
"mcpServers": {
"puppeteer-swarm": {
"command": "npx",
"args": ["-y", "puppeteer-swarm-mcp", "--tabs=5", "--headless"]
}
}
}Add this to your Zed settings.json:
{
"context_servers": {
"puppeteer-swarm": {
"source": "custom",
"command": "npx",
"args": ["-y", "puppeteer-swarm-mcp", "--tabs=5", "--headless"]
}
}
}Available Tools
launch
Initialize the browser and tab pool. Must be called before using any other browser tools.
Parameters: None
Returns:
{
"message": "브라우저가 성공적으로 시작되었습니다.",
"config": {
"tabCount": 5,
"headless": false,
"idleTimeout": 300000
}
}close
Close the browser and all tabs.
Parameters: None
Returns:
{
"message": "브라우저가 종료되었습니다."
}get_pool_status
Get the current status of the tab pool. Can be called before launch to check initialization status.
Parameters: None
Returns (after launch):
{
"initialized": true,
"total": 5,
"idle": 3,
"busy": 2
}Returns (before launch):
{
"initialized": false,
"message": "브라우저가 초기화되지 않았습니다. 먼저 'launch' 도구를 호출하세요."
}navigate
Allocate an idle tab and navigate to a URL.
Parameters:
Name | Type | Required | Description |
| string | Yes | URL to navigate to |
| string | No | Wait condition ( |
Returns:
{
"tabId": "tab-1",
"url": "https://example.com",
"title": "Example Domain"
}get_content
Extract HTML or text content from a page.
Parameters:
Name | Type | Required | Description |
| string | Yes | Target tab ID |
| string | No | Extract format ( |
Returns:
{
"content": "..."
}screenshot
Capture a page screenshot.
Parameters:
Name | Type | Required | Description |
| string | Yes | Target tab ID |
| boolean | No | Capture full page. Default: |
Returns: Image content (base64 PNG)
click
Click an element by CSS selector.
Parameters:
Name | Type | Required | Description |
| string | Yes | Target tab ID |
| string | Yes | CSS selector |
Returns:
{
"success": true
}type
Type text into an input field.
Parameters:
Name | Type | Required | Description |
| string | Yes | Target tab ID |
| string | Yes | CSS selector |
| string | Yes | Text to type |
Returns:
{
"success": true
}evaluate
Execute JavaScript in the page context.
Parameters:
Name | Type | Required | Description |
| string | Yes | Target tab ID |
| string | Yes | JavaScript code to execute |
Returns:
{
"result": "..."
}wait_for_selector
Wait for an element to appear in the DOM.
Parameters:
Name | Type | Required | Description |
| string | Yes | Target tab ID |
| string | Yes | CSS selector |
| number | No | Timeout in ms. Default: |
Returns:
{
"success": true
}release_tab
Release a tab back to idle state.
Parameters:
Name | Type | Required | Description |
| string | Yes | Tab ID to release |
Returns:
{
"success": true
}Workflow Example
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)Note: The browser does not start automatically. You must call
launchbefore using any browser tools.
Logging
Logs are stored in the logs/ directory:
File Pattern:
mcp-puppeteer-YYYY-MM-DD.logDaily rotation, max 20MB per file
14 days retention with auto-compression
License
MIT License - see the LICENSE file for details.
Author
Choi Sumin - GitHub
Available Tools
11 toolsclickC
지정된 셀렉터의 요소를 클릭합니다.
Inputs: tabId (required), selector (required).
closeA
브라우저를 종료하고 모든 탭을 닫습니다.
Inputs: no named parameters.
evaluateA
페이지 컨텍스트에서 JavaScript를 실행합니다. 단일 표현식(예: 'document.title', '1 + 1')은 자동으로 결과가 반환됩니다. 복잡한 스크립트는 'return' 문을 명시적으로 사용하세요.
Inputs: tabId (required), script (required).
get_contentB
페이지의 HTML 또는 텍스트 콘텐츠를 추출합니다.
Inputs: tabId (required), type.
get_pool_statusB
탭 풀의 현재 상태를 조회합니다.
Inputs: no named parameters.
launchA
브라우저와 탭 풀을 초기화합니다. 다른 브라우저 도구 사용 전에 반드시 호출해야 합니다.
Inputs: no named parameters.
release_tabC
사용 완료된 탭을 idle 상태로 반환합니다.
Inputs: tabId (required).
screenshotC
페이지 스크린샷을 캡처합니다.
Inputs: tabId (required), fullPage.
typeC
지정된 셀렉터의 입력 필드에 텍스트를 입력합니다.
Inputs: tabId (required), selector (required), text (required).
wait_for_selectorC
지정된 셀렉터가 DOM에 나타날 때까지 대기합니다.
Inputs: tabId (required), selector (required), timeout.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 11 tools
Each tool has a clearly distinct purpose with no overlap: click, type, and wait_for_selector handle user interactions; navigate, get_content, and screenshot manage page navigation and content; launch, close, get_pool_status, and release_tab control browser and tab lifecycle; evaluate executes JavaScript. The descriptions reinforce these distinctions, making misselection unlikely.
All tool names follow a consistent verb-based snake_case pattern (e.g., click, navigate, get_content, wait_for_selector). There are no deviations in style or convention, making the set predictable and easy to understand at a glance.
With 11 tools, the count is well-scoped for a Puppeteer automation server. It covers essential browser operations (launch, close), tab management (navigate, release_tab, get_pool_status), user interactions (click, type, wait_for_selector), content extraction (get_content, screenshot), and scripting (evaluate), with each tool earning its place.
The tool set provides complete coverage for browser automation: it includes lifecycle management (launch, close), navigation (navigate), user interactions (click, type, wait_for_selector), content handling (get_content, screenshot, evaluate), and tab pooling (get_pool_status, release_tab). No obvious gaps exist for typical Puppeteer workflows.
Maintenance
Related MCP Connectors
Control a real browser from AI agents: navigate, click, type, screenshot, read the page.
Provides cloud browser automation capabilities using Stagehand and Browserbase, enabling LLMs to i…
Hosted browser for agents: open pages, search the web, extract data, read PDFs and take screenshots.
Cloud browser, web extraction, screenshots, and remote CDP tools for AI agents.
Related MCP Servers
- AlicenseCqualityDmaintenanceEnables LLMs to perform web browsing tasks, take screenshots, and execute JavaScript using Puppeteer for browser automation.41MIT
- AlicenseAqualityDmaintenanceEnables browser automation with Puppeteer, supporting navigation, form interactions, and connection to active Chrome instances for comprehensive web page interaction.82,668 npm491MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI coding assistants to control and inspect a live Chrome browser through DevTools for automated testing, performance analysis, debugging, and web scraping. Provides reliable browser automation using Puppeteer with comprehensive DevTools access.3Apache 2.0
- AlicenseBqualityDmaintenanceEnables AI agents to automate browser interactions including navigation, content extraction, form filling, screenshots, and JavaScript execution across multiple tabs using Puppeteer.271MIT