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

Navigation

Interaction

Input

Content

Waiting

Media

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

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