Overview

The Puppeteer MCP Server enables AI models to control and interact with web browsers through a set of intuitive tools. Built on Puppeteer, this server allows language models to perform a wide range of browser automation tasks including navigation, element interaction, form filling, and JavaScript execution.

Installation

You can use the Puppeteer MCP Server in two ways:

Using Docker

The Docker implementation uses headless Chromium:

{
  "mcpServers": {
    "puppeteer": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "--init", "-e", "DOCKER_CONTAINER=true", "mcp/puppeteer"]
    }
  }
}

To build the Docker image:

docker build -t mcp/puppeteer -f src/puppeteer/Dockerfile .

Using NPX

The NPX version will open a browser window:

{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-puppeteer"]
    }
  }
}

Available Tools

puppeteer_navigate

Navigate to any URL in the browser.

Parameters:

• url (string): The URL to navigate to

Example:

{
  "url": "https://example.com"
}

puppeteer_screenshot

Capture screenshots of the entire page or specific elements.

Parameters:

• name (string, required): Name for the screenshot
• selector (string, optional): CSS selector for element to screenshot
• width (number, optional, default: 800): Screenshot width
• height (number, optional, default: 600): Screenshot height

Example:

{
  "name": "homepage",
  "selector": "#main-content",
  "width": 1024,
  "height": 768
}

puppeteer_click

Click elements on the page.

Parameters:

• selector (string): CSS selector for element to click

Example:

{
  "selector": ".submit-button"
}

puppeteer_hover

Hover over elements on the page.

Parameters:

• selector (string): CSS selector for element to hover

Example:

{
  "selector": ".dropdown-menu"
}

puppeteer_fill

Fill out input fields.

Parameters:

• selector (string): CSS selector for input field
• value (string): Value to fill

Example:

{
  "selector": "#search-input",
  "value": "search query"
}

puppeteer_select

Select an option from a dropdown menu.

Parameters:

• selector (string): CSS selector for element to select
• value (string): Value to select

Example:

{
  "selector": "#country-select",
  "value": "US"
}

puppeteer_evaluate

Execute JavaScript in the browser console.

Parameters:

• script (string): JavaScript code to execute

Example:

{
  "script": "document.querySelectorAll('.item').length"
}

Resources

The server provides access to two types of resources:

1. Console Logs (console://logs)

   • Browser console output in text format
   • Includes all console messages from the browser

2. Screenshots (screenshot://<name>)

   • PNG images of captured screenshots
   • Accessible via the screenshot name specified during capture

Use Cases

• Web scraping and data extraction
• Automated testing of web applications
• Form submission and interaction
• Capturing visual content from websites
• Executing custom JavaScript on web pages
• Monitoring web console output

License

This MCP server is licensed under the MIT License, allowing free use, modification, and distribution subject to the license terms.