Twolven MCP Server Puppeteer Py

🚀 Puppeteer MCP Server with Playwright (Python Implementation)

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

🚀 Quick Start

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

✨ Features

• Full browser automation
• Page navigation
• Screenshot capture (full page or specific 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 the Playwright browsers:

playwright install

💻 Usage Examples

Starting the Server

Run the server directly:

python puppeteer_server.py

Claude Desktop Configuration

Add the following to the Claude configuration file:

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

Available Tools

puppeteer_navigate

Navigate to any URL in the browser.

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

puppeteer_screenshot

Capture a screenshot of the full 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 an element on the page.

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

puppeteer_fill

Fill 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 covering common scenarios:

• Navigation failure
• Element not found
• Timeout errors
• JavaScript execution failure

Logging

Debugging and monitoring are done through console output, making it easy to troubleshoot issues.

Project Structure

puppeteer_server/
├── server.py        # Main server file
├── utils.py         # Utility functions
├── requirements.txt # Dependency management
└── README.md        # Project documentation

Example Usage

Filling a form and capturing a screenshot

from playwright.sync_playwright import sync_playwright

def main():
    with sync_playwright() as p:
        browser = p.chromium.launch()
        page = browser.new_page()
        
        # Navigate to the page
        page.goto('https://example.com')
        
        # Fill the form
        page.fill('#username', 'admin')
        page.fill('#password', 'secret')
        
        # Submit the form
        page.click('button[type="submit"]')
        
        # Capture a screenshot
        page.screenshot(path='screenshot.png', quality=100)
        
        browser.close()

if __name__ == "__main__":
    main()

🤝 Contribution Guidelines

Contributions are welcome! Please fork the repository and submit a PR.

📄 License

[Insert license information here]

Thank you for using the Puppeteer MCP Server! If you need help or have feedback, please contact the maintenance team.