MCP Master Puppeteer Server

You run an MCP server that automates browser tasks with Puppeteer while keeping responses concise for agent processing. It delivers flexible data returns and supports on-demand enrichment so you can balance speed and detail when you need it.

How to use

You interact with the Puppeteer MCP server through your MCP client by invoking the available tools to navigate pages, extract content, take targeted screenshots, analyze forms, and perform multi-step interactions. Start with the minimal tool set for fast responses and enable additional data only when you need richer context for decision making.

Key usage patterns you can apply include navigating to a page for quick checks, extracting structured content for summaries, capturing screenshots optimized for processing by language models, and performing batch interactions to simulate user flows. Each tool is designed to return only the essential data by default, with optional flags to enrich the result when required.

How to install

Prerequisites: you need Node.js and npm installed on your machine. Make sure you have permission to install global packages if you plan to use npx to run commands.

npm install mcp-master-puppeteer

npx mcp-master-puppeteer

Configuration

Configure your MCP settings to run the Puppeteer MCP server as a local process. The server is started by invoking the runtime command with its arguments, and you can pass environment variables to customize Puppeteer behavior.

{
  "mcpServers": {
    "puppeteer": {
      "command": "mcp-master-puppeteer",
      "args": [],
      "env": {
        "PUPPETEER_ARGS": "{\"headless\": false}"
      }
    }
  }
}

Notes on usage and behavior

The server aims to minimize token usage by default. You will get the essential navigation and page data first, with optional enrichment available through flags and settings. Use the smallest data return that satisfies your task, and opt into richer metadata, performance metrics, or full content only when necessary.

Example tool access overview

The following tools are available for browser automation and data extraction. You can mix and match to build your automation: watch pages, extract content, create screenshots, analyze forms, batch interact, and perform simple actions like click and fill.

Security and best practices

Run the Puppeteer MCP server with least-privilege settings. When enabling headful mode for debugging, ensure your environment is isolated from untrusted content. Always validate and sanitize any content you extract before displaying it to end users.

Troubleshooting

If you encounter issues starting the server, verify that the runtime command is accessible and the environment variables are correctly set. Check for common Puppeteer launch errors related to sandboxing, proxies, or headless vs headful mode, and adjust PUPPETEER_ARGS accordingly.

Examples of common workflows

Navigate to a page and quickly inspect its status and title without pulling full content, then opt into content extraction if deeper analysis is needed.

Available tools summary

puppeteer_navigate_analyze, puppeteer_screenshot_plus, puppeteer_extract_content, puppeteer_get_page_info, puppeteer_analyze_forms, puppeteer_batch_interact, puppeteer_click, puppeteer_fill.

Available tools

puppeteer_navigate_analyze

Navigate to a URL and return the final URL, status, title, and a minimal data payload. You can request additional content and performance metadata as needed.

puppeteer_screenshot_plus

Capture screenshots optimized for large language models with automatic resizing to stay within dimension limits. Supports single or multiple images and different formats.

puppeteer_extract_content

Extract structured content from the page with options for format, selector scope, and optional analysis of structure.

puppeteer_get_page_info

Gather comprehensive page metadata, SEO signals, accessibility metrics, and performance indicators to assess page quality.

puppeteer_analyze_forms

Analyze all forms on the current page to collect field details, validation hints, and inferred form purposes.

puppeteer_batch_interact

Execute a sequence of interactions (clicks, typing, scrolling) and return per-action results along with any navigations.

puppeteer_click

Click an element specified by a CSS selector.

puppeteer_fill

Fill an input field identified by a CSS selector with a given value.