MCP Puppeteer

🚀 Shadow Puppetry Toolkit

A Model Context Protocol server that provides browser automation capabilities using Puppeteer. This server enables LLMs to interact with web pages, take screenshots, and execute JavaScript in a real browser environment.

🚀 Quick Start

The Shadow Puppetry Toolkit is a powerful Model Context Protocol server that leverages Puppeteer to automate browser operations. It allows LLMs to perform various tasks in a real - world browser setting.

✨ Features

• Browser automation
• Console log monitoring
• Screenshot functionality
• JavaScript execution
• Basic web page interactions (navigation, clicking, form filling)

📦 Installation

Docker

⚠️ Important Note

The Docker implementation will use headless Chromium, while the NPX version will open a browser window.

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

NPX

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

💻 Usage Examples

Tools

• puppeteer_navigate

  • Navigate to any URL in the browser.
  • Input: url (string)

• puppeteer_screenshot

  • Take a screenshot of the page or a specific element.
  • Input:
    • name (string, required): The name of the screenshot.
    • selector (string, optional): The CSS selector of the element to capture.
    • width (number, optional, default: 800): The width of the screenshot.
    • height (number, optional, default: 600): The height of the screenshot.

• puppeteer_click

  • Click on an element on the page.
  • Input: selector (string): The selector of the element to click.

• puppeteer_hover

  • Hover the mouse over an element on the page.
  • Input: selector (string): The selector of the element to hover over.

• puppeteer_fill

  • Fill an input field.
  • Input:
    • selector (string): The selector of the input field.
    • value (string): The value to fill.

• puppeteer_select

  • Select an element in a SELECT tag.
  • Input:
    • selector (string): The selector of the element to select.
    • value (string): The value to select.

• puppeteer_evaluate

  • Execute JavaScript in the browser console.
  • Input: script (string): The JavaScript code to execute.

Resources

The server provides two types of resources:

1. Console Logs (console://logs)

   • Text - formatted output from the browser console.
   • Includes all console messages in the browser.

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

   • PNG image screenshots with a specified name.
   • Access the captured screenshots by the screenshot name.

🔧 Technical Details

Build

Docker build:

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

📄 License

This MCP server is released under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please refer to the LICENSE file in the project repository.