Puppeteer MCP Server

A Model Context Protocol (MCP) server that provides browser automation capabilities through Puppeteer. This server enables AI agents to interact with web pages, take screenshots, execute JavaScript, and perform various browser operations.

Features

• Multi-tab Support: Manage multiple browser tabs with unique IDs
• Comprehensive Tools: 27 tools for navigation, interaction, content extraction, and more
• Dual Transport: Supports both stdio (for Claude Desktop/Code) and HTTP transports
• Result Types: Consistent error handling with structured Result types

Installation

npm install
npm run build

Usage

Stdio Mode (Default)

For use with Claude Desktop or Claude Code:

npm start
# or
node dist/index.js

HTTP Mode

For remote or containerized deployments:

npm start -- --http
# or
node dist/index.js --http --port=3000

Claude Desktop Configuration

Add to your Claude Desktop config:

{
  "mcpServers": {
    "puppeteer": {
      "command": "node",
      "args": ["/path/to/puppeteer-mcp/dist/index.js"]
    }
  }
}

Available Tools

Tab Management

Tool	Description
list_tabs	List all open browser tabs
new_tab	Create a new tab (optionally with URL)
close_tab	Close a tab
switch_tab	Switch to a different tab

Navigation

Tool	Description
navigate	Navigate to a URL
reload	Reload the current page
go_back	Navigate back in history
go_forward	Navigate forward in history

Interaction

Tool	Description
click	Click an element
fill	Fill a text input
select	Select dropdown option(s)
hover	Hover over an element
focus	Focus an element

Input

Tool	Description
keyboard	Press keyboard keys
mouse	Perform mouse actions
scroll	Scroll the page or element

Content

Tool	Description
evaluate	Execute JavaScript
get_content	Get page/element HTML or text
query_selector	Get element information

Waiting

Tool	Description
wait_for_selector	Wait for element to appear
wait_for_navigation	Wait for navigation
wait	Wait for specified time

Media

Tool	Description
screenshot	Capture screenshot
pdf	Generate PDF

Cookies

Tool	Description
get_cookies	Get cookies
set_cookies	Set cookies
delete_cookies	Delete cookies

Tool Parameters

All tools that operate on pages accept an optional tabId parameter. If not specified, the active tab is used.

Example: Navigate and Take Screenshot

// Navigate
{ "name": "navigate", "arguments": { "url": "https://example.com" } }

// Take screenshot
{ "name": "screenshot", "arguments": { "fullPage": true, "format": "png" } }

Example: Multi-tab Workflow

// Create new tab
{ "name": "new_tab", "arguments": { "url": "https://site-a.com" } }
// Returns: { "id": "tab_abc123", "url": "https://site-a.com", ... }

// Create another tab
{ "name": "new_tab", "arguments": { "url": "https://site-b.com" } }
// Returns: { "id": "tab_def456", "url": "https://site-b.com", ... }

// List all tabs
{ "name": "list_tabs", "arguments": {} }

// Interact with specific tab
{ "name": "click", "arguments": { "selector": "button", "tabId": "tab_abc123" } }

Environment Variables

Variable	Description	Default
PORT	HTTP server port	3000
HEADLESS	Run browser headless	true
TIMEOUT	Default operation timeout (ms)	30000

Development

# Install dependencies
npm install

# Run in development mode
npm run dev

# Type check
npm run typecheck

# Run tests
npm test

# Build
npm run build

Architecture

src/
├── index.ts          # Entry point, transport setup
├── server.ts         # MCP server configuration
├── browser.ts        # Browser lifecycle management
├── tabs.ts           # Multi-tab state management
├── types.ts          # TypeScript interfaces
├── errors.ts         # Result types and error handling
├── schemas.ts        # Zod validation schemas
└── tools/
    ├── tab-tools.ts      # Tab management tools
    ├── navigation.ts     # Navigation tools
    ├── interaction.ts    # Click, fill, select, etc.
    ├── content.ts        # Evaluate, get content
    ├── waiting.ts        # Wait tools
    ├── media.ts          # Screenshot, PDF
    ├── cookies.ts        # Cookie management
    └── input.ts          # Keyboard, mouse, scroll

License

MIT

puppeteer-mcp