MCP Server Puppeteer Py

🚀 Puppeteer MCP Server (Python Implementation)

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

🚀 Quick Start

This Python implementation offers a stable alternative to the TypeScript version, providing the same functionality with better error handling and logging. It uses Playwright, the Python equivalent of Puppeteer, to offer powerful browser automation capabilities.

✨ Features

• Full browser automation
• Page navigation
• Screenshot capture (full page or element)
• Form interaction (clicking and filling)
• JavaScript execution
• Console log monitoring
• Configurable timeouts
• Detailed error handling
• Comprehensive logging

📦 Installation

Prerequisites

• Python 3.8+
• pip (Python package installer)

Steps

1. Install the required packages:

pip install -r requirements.txt

2. Install Playwright browsers:

playwright install

💻 Usage Examples

Start the Server

Run the server directly:

python puppeteer_server.py

Claude Desktop Configuration

Add the following content to the Claude configuration file:

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

Available Tools

puppeteer_navigate

Navigate to any URL.

{
  "name": "puppeteer_navigate",
  "arguments": {
    "url": "https://example.com",
    "timeout": 60000  // Optional, default is 60000ms
  }
}

puppeteer_screenshot

Take a screenshot of a web page or a specific element.

{
  "name": "puppeteer_screenshot",
  "arguments": {
    "name": "my_screenshot",
    "selector": "#specific-element",  // Optional
    "width": 1280,  // Optional, default: 1280
    "height": 720,  // Optional, default: 720
    "timeout": 30000  // Optional, default is 30000ms
  }
}

puppeteer_click

Click on an element on the page.

{
  "name": "puppeteer_click",
  "arguments": {
    "selector": ".button-class",
    "timeout": 30000  // Optional, default is 30000ms
  }
}

puppeteer_fill

Fill in an input field.

{
  "name": "puppeteer_fill",
  "arguments": {
    "selector": "#input-id",
    "value": "Text to fill",
    "timeout": 30000  // Optional, default is 30000ms
  }
}

puppeteer_evaluate

Execute JavaScript in the browser console.

{
  "name": "puppeteer_evaluate",
  "arguments": {
    "script": "document.title",
    "timeout": 30000  // Optional, default is 30000ms
  }
}

🔧 Technical Details

Error Handling

The server provides detailed error messages for the following scenarios:

• Navigation failure
• Element not found
• Timeout errors

Logging

Logs are divided into three levels:

• INFO: Messages for normal operations.
• ERROR: Error or exception situations.
• DEBUG: Detailed debugging information.

By default, the browser runs in non-headless mode, which is very useful for debugging. In a production environment, you may need to switch to headless mode for better performance.

Configurable Timeouts

You can adjust the waiting time according to specific requirements to avoid script freezes caused by network delays or other issues.

This project offers comprehensive functionality and good documentation, making it suitable for developers who need browser automation tasks. In particular, the support for Playwright ensures efficient web interaction operations even in a Python environment.