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

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 Server

Puppeteer MCP Server

Features

Installation

Usage

Stdio Mode (Default)

HTTP Mode

Claude Desktop Configuration

Available Tools

Tab Management

Navigation

Interaction

Input

Content

Waiting

Media

Cookies

Tool Parameters

Example: Navigate and Take Screenshot

Example: Multi-tab Workflow

Environment Variables

Development

Architecture

License

puppeteer-mcp

Resources

Tools

New MCP Servers

Latest Blog Posts

MCP directory API