twolven/mcp-server-puppeteer-py

A Model Context Protocol server that provides browser automation capabilities using Playwright (Python's equivalent to Puppeteer). This server enables LLMs to interact with web pages, take screenshots, and execute JavaScript in a real browser environment.
## Overview
This Python implementation provides a stable alternative to the TypeScript version, offering the same capabilities with improved error handling and logging. It uses Playwright, which is the Python equivalent to Puppeteer, providing robust browser automation capabilities.
## Key Features
Full browser automation
Page navigation
Screenshot capture (full page or elements)
Form interaction (clicking and filling)
JavaScript execution
Console log monitoring
Configurable timeouts
Detailed error handling
Comprehensive logging
## Prerequisites
Python 3.8+
pip (Python package installer)
## Installation
1. Install the required packages:
bash
pip install -r requirements.txt
2. Install Playwright browsers:
bash
playwright install
## Usage
### Starting the Server
Run the server directly:
bash
python puppeteerserver.py
### Claude Desktop Configuration
Add this to your Claude configuration file:
json
"mcpServers": {
"puppeteer": {
"command": "python",
"args": ["path/to/puppeteer.py"]
## Available Tools
### puppeteernavigate
Navigate to any URL in the browser.
json
"name": "puppeteernavigate",
"arguments": {
"url": "https://example.com",
"timeout": 60000 // optional, defaults to 60000ms
### puppeteerscreenshot
Capture screenshots of the entire page or specific elements.
json
"name": "puppeteerscreenshot",
"arguments": {
"name": "myscreenshot",
"selector": "#specific-element", // optional
"width": 1280, // optional, default: 1280
"height": 720, // optional, default: 720
"timeout": 30000 // optional, defaults to 30000ms
### puppeteerclick
Click elements on the page.
json
"name": "puppeteerclick",
"arguments": {
"selector": ".button-class",
"timeout": 30000 // optional, defaults to 30000ms
### puppeteerfill
Fill out input fields.
json
"name": "puppeteerfill",
"arguments": {
"selector": "#input-id",
"value": "text to fill",
"timeout": 30000 // optional, defaults to 30000ms
### puppeteerevaluate
Execute JavaScript in the browser console.
json
"name": "puppeteerevaluate",
"arguments": {
"script": "document.title",
"timeout": 30000 // optional, defaults to 30000ms
## Error Handling
The server provides detailed error messages for common scenarios:
Navigation failures
Element not found
Timeout errors
JavaScript execution errors
Screenshot failures