Puppeteer MCP Server

# 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 ```bash npm install npm run build ``` ## Usage ### Stdio Mode (Default) For use with Claude Desktop or Claude Code: ```bash npm start # or node dist/index.js ``` ### HTTP Mode For remote or containerized deployments: ```bash npm start -- --http # or node dist/index.js --http --port=3000 ``` ## Claude Desktop Configuration Add to your Claude Desktop config: ```json { "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 ```json // Navigate { "name": "navigate", "arguments": { "url": "https://example.com" } } // Take screenshot { "name": "screenshot", "arguments": { "fullPage": true, "format": "png" } } ``` ### Example: Multi-tab Workflow ```json // 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 ```bash # 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