Puppeteer

You run a small, Python-based MCP server that drives a real browser via Playwright, letting language models automate web pages, take screenshots, fill forms, click elements, and run JavaScript. This server is useful for tasks that require interacting with live pages in a controlled, scriptable way.

How to use

You connect your MCP client to this server to perform browser automation tasks. Use it to navigate to web pages, capture screenshots (full page or specific elements), click and fill form fields, execute JavaScript, and monitor console output. The server is designed to provide clear error messages and robust logging to help you diagnose issues during automation.

How to install

Prerequisites you need before running the server:

• Python 3.8+
• pip (Python package installer)

Install the required Python dependencies and Playwright browsers to enable full browser automation.

pip install -r requirements.txt

Then install Playwright’s browser binaries so you can automate real browsers.

playwright install

Start the server when you’re ready to automate browsers.

python puppeteer_server.py

If you want to configure a client (Claude Desktop in this example) to connect to the server, add this MCP configuration to your client settings.

{
  "mcpServers": {
    "puppeteer": {
      "command": "python",
      "args": ["path/to/puppeteer.py"]
    }
  }
}

Notes and configuration details

The server launches browsers in non-headless mode to aid debugging. The default viewport is 1280x720, and all timeouts are configurable. Console output from the browser is captured and stored, and screenshots are kept in memory as base64-encoded data. The server includes detailed error handling for navigation issues, missing elements, timeouts, JavaScript errors, and screenshot failures. Logging covers INFO, ERROR, and DEBUG levels to help you trace operations.

• Browser launches in non-headless mode for easier debugging
• Default viewport size is 1280x720
• All timeouts are configurable
• Console logs are captured and stored
• Screenshots are stored in memory as base64
• Detailed error messages for common scenarios
• Comprehensive logging with INFO, ERROR, and DEBUG levels

Available tools

puppeteer_navigate

Navigate to a given URL in the browser with an optional timeout to control how long the server waits for page load.

puppeteer_screenshot

Capture screenshots of the entire page or a specific element, with options for name, selector, dimensions, and timeout.

puppeteer_click

Click a page element identified by a selector, with an optional timeout to handle loading or visibility issues.

puppeteer_fill

Fill input fields by selector with a provided value, including an optional timeout for element readiness.

puppeteer_evaluate

Execute a JavaScript snippet in the browser context and return the result, with an optional timeout for execution.