andytango/puppeteer-mcp

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