MCP Configurable Puppeteer

🚀 Configurable Puppeteer MCP Server

A Model Context Protocol server that uses Puppeteer to enable browser automation capabilities and provides configurable options. This server allows large language models to interact with web pages, take screenshots, and execute JavaScript. It can run in a real browser environment and supports customizing Puppeteer startup options through environment variables.

🛠️ Components

Tools

• puppeteer_navigate

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

• puppeteer_screenshot

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

• puppeteer_click

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

• puppeteer_hover

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

• puppeteer_fill

  • Fill a form field.
  • Input:
    • selector (string): The CSS selector of the input field.
    • value (string): The value to be filled.

• puppeteer_select

  • Select an element with the SELECT tag.
  • Input:
    • selector (string): The CSS selector of the element to be selected.
    • value (string): The value to be selected.

• puppeteer_evaluate

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

Resources

The server provides two types of resources:

1. Console Logs (console://logs)

   • The browser console output in text format.
   • Contains all console messages from the browser.

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

   • Page screenshots in PNG format.
   • Accessed by the screenshot name specified during capture.

✨ Features

• Browser automation
• Console log monitoring
• Screenshot capability
• JavaScript execution
• Basic web page interaction (navigation, click, form filling)
• Configure Puppeteer options via environment variables

⚙️ Configuration

Using Custom Puppeteer Options

You can configure Puppeteer startup options by providing a JSON string in the PUPPETEER_ARGS environment variable. This allows you to customize browser behavior without modifying the server code.

Example: Using Firefox Instead of Chrome

{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": ["-y", "github:afshawnlotfi/mcp-configurable-puppeteer"],
      "env": {
        "PUPPETEER_ARGS": "{\"browser\": \"firefox\"}"
      }
    }
  }
}

Example: Configuring the Browser Window Size

{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": ["-y", "github:afshawnlotfi/mcp-configurable-puppeteer"],
      "env": {
        "PUPPETEER_ARGS": "{\"defaultViewport\": {\"width\": 1280, \"height\": 800}}"
      }
    }
  }
}

Standard Configuration

{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": ["-y", "github:afshawnlotfi/mcp-configurable-puppeteer"]
    }
  }
}

📄 License

This project is licensed under the MIT License.