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