pmind-playwright-mcp

PMIND Playwright MCP Server

⚠️ Experimental: This MCP server is in an experimental state and may have rough edges. Please report any issues you encounter.

A Python implementation of a browser automation MCP (Model Context Protocol) server using FastMCP and Playwright. This server provides comprehensive tools to interact with web pages, take screenshots, and execute JavaScript in a real browser environment with advanced features like stealth mode and mobile device emulation.

🎯 Features

This MCP server provides browser automation capabilities with advanced anti-detection measures and mobile emulation support.

📦 Core Capabilities

• 🌐 Navigation: Navigate to URLs with configurable timeouts and device emulation
• 📸 Screenshots: Capture full page or element screenshots (automatically saved to ~/.pmind-playwright-mcp/screenshots)
• 🎥 Video Recording: Record browser sessions across multiple navigations
• 🖱️ Interactions: Click elements and fill forms programmatically
• 💻 JavaScript: Execute custom JavaScript in the browser context
• 📱 Mobile Emulation: Full device emulation (iPhone, Android, tablets)
• 🥷 Stealth Mode: Anti-bot detection with playwright-stealth
• 🔍 Console Monitoring: Capture and store browser console logs

✨ Key Features

• 🏗️ FastMCP Framework: Built on FastMCP for robust MCP implementation
• 🔒 Type Safety: Pydantic models for input validation and configuration
• ⚙️ Configurable: Environment-based configuration with dotenv support
• 🎭 Playwright Backend: Using Playwright for reliable browser automation
• 🛡️ Security First: Removed dangerous browser flags, custom exception handling
• 📁 Organized Architecture: Clean service-based structure with proper separation of concerns
• 💾 Persistent Storage: All screenshots and videos saved to ~/.pmind-playwright-mcp/

Installation & Setup

Step 1: Clone the Repository

git clone https://github.com/raveenplgithub/pmind-playwright-mcp.git
cd pmind-playwright-mcp

Step 2: Install Dependencies

# Install dependencies using uv
uv sync

# Install Playwright browsers (required for browser automation)
uv run playwright install

Step 3: Configure the Server

The server uses environment variables for configuration. Copy the example .env file and customize as needed:

cp .env.example .env

To customize settings, edit .env:

# Browser Settings
BROWSER_HEADLESS=false  # Set to true for headless mode
BROWSER_VIEWPORT_WIDTH=1280
BROWSER_VIEWPORT_HEIGHT=720

# See .env.example for all available options

Step 4: Configure with Your Client

Add the MCP server to your client's MCP configuration:

{
  "mcpServers": {
    "pmind-playwright-mcp": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/pmind-playwright-mcp", "pmind-playwright-mcp"]
    }
  }
}

Replace /path/to/pmind-playwright-mcp with the actual path where you cloned the repository.

For Claude Code (CLI)

Use the following command to add the server:

claude mcp add pmind-playwright-mcp -- uv run --directory /path/to/pmind-playwright-mcp pmind-playwright-mcp

Configuration Options

Storage Locations

All media files are saved to ~/.pmind-playwright-mcp/:

• Screenshots: ~/.pmind-playwright-mcp/screenshots/
• Videos: ~/.pmind-playwright-mcp/videos/

These directories are created automatically when needed.

Configuration File Structure

The .env file controls all server settings:

• Browser Settings: Headless mode, viewport size, launch arguments
• Context Settings: Locale, timezone, permissions, color scheme
• Timeouts: Default, navigation, page load check, network idle
• Screenshots: Save directory and timestamp format
• Stealth Mode: Anti-detection feature toggles
• Mobile Defaults: Default device for mobile emulation
• Logging: Log level and format
• Video Recording: Video directory and dimensions

See .env.example for detailed documentation of each option and available environment variables.

Usage

Once configured, you can start using the Playwright MCP server through your client. The server will automatically start when your client connects.

Available Tools

• playwright_navigate - Navigate to URLs with optional device emulation and video recording
• playwright_screenshot - Capture screenshots of pages or specific elements
• playwright_click - Click elements on the page
• playwright_fill - Fill input fields with text
• playwright_evaluate - Execute JavaScript in the browser context
• playwright_stop_recording - Stop and save video recordings
• playwright_list_videos - List all saved video recordings

Video Recording Example

To record a browsing session across multiple sites:

1. Start recording with the first navigation:

   playwright_navigate(url="https://example.com", record_video=true)
   

2. Continue recording while navigating to other sites:

   playwright_navigate(url="https://another-site.com", record_video=true)
   

3. Stop recording and save the video:

   playwright_stop_recording(session_name="my_browsing_session")
   

The video will be saved to ~/.pmind-playwright-mcp/videos/my_browsing_session_[timestamp].webm

Manual Server Testing

To test the server manually:

# Run the MCP server
uv run pmind-playwright-mcp

Development

Running Tests

# Install dev dependencies
uv sync --dev

# Run tests (when available)
uv run pytest

Code Quality

# Format code
uv run black .
uv run ruff check --fix .

# Check code quality
uv run black --check .
uv run ruff check .

Architecture

• src/server.py: FastMCP server implementation with tool definitions and entry point
• src/config.py: Pydantic configuration models with dotenv support
• src/services/browser.py: Browser service managing Playwright instances
• .env: Environment variables configuration file
• .env.example: Example configuration file with all available options