# 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`/`close` tools
- **Tab 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
## Installation
### Option 1: Install from npm
```bash
npm install -g puppeteer-swarm-mcp
```
Or run directly using npx:
```bash
npx puppeteer-swarm-mcp
```
### Option 2: Install from source
```bash
git clone https://github.com/greatSumini/puppeteer-swarm-mcp.git
cd puppeteer-swarm-mcp
npm install
npm run build
```
## Usage
```bash
# 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
```
### Environment Variables
```bash
TAB_COUNT=10 HEADLESS=true puppeteer-swarm-mcp
```
## MCP 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.)
<details>
<summary><b>Install in Claude Code</b></summary>
Run this command:
```sh
claude mcp add puppeteer-swarm -- npx -y puppeteer-swarm-mcp --tabs=5 --headless
```
Or with custom options:
```sh
claude mcp add puppeteer-swarm -- npx -y puppeteer-swarm-mcp --tabs=10
```
</details>
<details>
<summary><b>Install in Cursor</b></summary>
Go to: `Settings` -> `Cursor Settings` -> `MCP` -> `Add new global MCP server`
Add the following configuration to your `~/.cursor/mcp.json` file:
```json
{
"mcpServers": {
"puppeteer-swarm": {
"command": "npx",
"args": ["-y", "puppeteer-swarm-mcp", "--tabs=5", "--headless"]
}
}
}
```
</details>
<details>
<summary><b>Install in Claude Desktop</b></summary>
Add the following to your Claude Desktop configuration file:
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"puppeteer-swarm": {
"command": "npx",
"args": ["-y", "puppeteer-swarm-mcp", "--tabs=5", "--headless"]
}
}
}
```
</details>
<details>
<summary><b>Install in VS Code</b></summary>
Add this to your VS Code MCP config file. See [VS Code MCP docs](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) for more info.
```json
"mcp": {
"servers": {
"puppeteer-swarm": {
"type": "stdio",
"command": "npx",
"args": ["-y", "puppeteer-swarm-mcp", "--tabs=5", "--headless"]
}
}
}
```
</details>
<details>
<summary><b>Install in Windsurf</b></summary>
Add this to your Windsurf MCP config file:
```json
{
"mcpServers": {
"puppeteer-swarm": {
"command": "npx",
"args": ["-y", "puppeteer-swarm-mcp", "--tabs=5", "--headless"]
}
}
}
```
</details>
<details>
<summary><b>Install in Cline</b></summary>
1. Open **Cline**
2. Click the hamburger menu icon (☰) to enter the **MCP Servers** section
3. Choose **Remote Servers** tab
4. Click the **Edit Configuration** button
5. Add puppeteer-swarm to `mcpServers`:
```json
{
"mcpServers": {
"puppeteer-swarm": {
"command": "npx",
"args": ["-y", "puppeteer-swarm-mcp", "--tabs=5", "--headless"]
}
}
}
```
</details>
<details>
<summary><b>Install in Zed</b></summary>
Add this to your Zed `settings.json`:
```json
{
"context_servers": {
"puppeteer-swarm": {
"source": "custom",
"command": "npx",
"args": ["-y", "puppeteer-swarm-mcp", "--tabs=5", "--headless"]
}
}
}
```
</details>
## Available Tools
### launch
Initialize the browser and tab pool. **Must be called before using any other browser tools.**
**Parameters**: None
**Returns**:
```json
{
"message": "브라우저가 성공적으로 시작되었습니다.",
"config": {
"tabCount": 5,
"headless": false,
"idleTimeout": 300000
}
}
```
---
### close
Close the browser and all tabs.
**Parameters**: None
**Returns**:
```json
{
"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):
```json
{
"initialized": true,
"total": 5,
"idle": 3,
"busy": 2
}
```
**Returns** (before launch):
```json
{
"initialized": false,
"message": "브라우저가 초기화되지 않았습니다. 먼저 'launch' 도구를 호출하세요."
}
```
---
### navigate
Allocate an idle tab and navigate to a URL.
**Parameters**:
| Name | Type | Required | Description |
|------|------|----------|-------------|
| `url` | string | Yes | URL to navigate to |
| `waitUntil` | string | No | Wait condition (`load`, `domcontentloaded`, `networkidle0`, `networkidle2`) |
**Returns**:
```json
{
"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 |
|------|------|----------|-------------|
| `tabId` | string | Yes | Target tab ID |
| `type` | string | No | Extract format (`html`, `text`). Default: `text` |
**Returns**:
```json
{
"content": "..."
}
```
---
### screenshot
Capture a page screenshot.
**Parameters**:
| Name | Type | Required | Description |
|------|------|----------|-------------|
| `tabId` | string | Yes | Target tab ID |
| `fullPage` | boolean | No | Capture full page. Default: `false` |
**Returns**: Image content (base64 PNG)
---
### click
Click an element by CSS selector.
**Parameters**:
| Name | Type | Required | Description |
|------|------|----------|-------------|
| `tabId` | string | Yes | Target tab ID |
| `selector` | string | Yes | CSS selector |
**Returns**:
```json
{
"success": true
}
```
---
### type
Type text into an input field.
**Parameters**:
| Name | Type | Required | Description |
|------|------|----------|-------------|
| `tabId` | string | Yes | Target tab ID |
| `selector` | string | Yes | CSS selector |
| `text` | string | Yes | Text to type |
**Returns**:
```json
{
"success": true
}
```
---
### evaluate
Execute JavaScript in the page context.
**Parameters**:
| Name | Type | Required | Description |
|------|------|----------|-------------|
| `tabId` | string | Yes | Target tab ID |
| `script` | string | Yes | JavaScript code to execute |
**Returns**:
```json
{
"result": "..."
}
```
---
### wait_for_selector
Wait for an element to appear in the DOM.
**Parameters**:
| Name | Type | Required | Description |
|------|------|----------|-------------|
| `tabId` | string | Yes | Target tab ID |
| `selector` | string | Yes | CSS selector |
| `timeout` | number | No | Timeout in ms. Default: `30000` |
**Returns**:
```json
{
"success": true
}
```
---
### release_tab
Release a tab back to idle state.
**Parameters**:
| Name | Type | Required | Description |
|------|------|----------|-------------|
| `tabId` | string | Yes | Tab ID to release |
**Returns**:
```json
{
"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 `launch` before using any browser tools.
## Logging
Logs are stored in the `logs/` directory:
- File Pattern: `mcp-puppeteer-YYYY-MM-DD.log`
- Daily rotation, max 20MB per file
- 14 days retention with auto-compression
## License
MIT License - see the [LICENSE](LICENSE) file for details.
## Author
**Choi Sumin** - [GitHub](https://github.com/greatSumini)
