Playwright MCP Server

A production-ready Model Context Protocol (MCP) server that provides browser automation capabilities using Playwright. Built with the mcp-use framework for enhanced developer experience with built-in Inspector UI and comprehensive error handling.

Overview

This MCP server exposes 6 powerful browser automation tools that allow AI assistants like Claude to interact with web pages, extract information, and perform automated testing. All operations are performed in a managed Chromium browser instance with robust error handling and timeout management.

Key Features:

• 🎭 Playwright Integration - Full async Playwright API support
• 🔍 Built-in Inspector UI - Test tools interactively at http://localhost:8000/inspector
• 📡 Auto-discovery - OpenMCP metadata endpoint at /openmcp.json
• 🛡️ Robust Error Handling - Clear, actionable error messages with suggestions
• 🔄 Crash Recovery - Automatic browser restart on failures
• ⚙️ Highly Configurable - All timeouts and settings via environment variables
• 🐛 Debug Mode - Enhanced logging and /docs endpoint

Features

6 Browser Automation Tools

1. navigate - Navigate to URLs with configurable wait conditions
2. click_element - Click elements by CSS selector
3. fill_input - Fill form inputs with text
4. extract_text - Extract text content from elements
5. screenshot - Take viewport or full-page screenshots
6. get_page_info - Get current page URL, title, and viewport size

All tools return standardized responses with either success data or detailed error information.

Installation

Prerequisites

• Python 3.13 or higher
• pip (Python package manager)

Setup

1. Clone or download this repository

cd "C:\Users\David Jr\playwright-mcp-server"

2. Create a virtual environment

python -m venv venv

3. Activate the virtual environment

Windows:

venv\Scripts\activate

macOS/Linux:

source venv/bin/activate

4. Install dependencies

pip install -r requirements.txt

5. Install Playwright browsers

playwright install chromium

6. Configure environment variables

# Windows
copy .env.example .env

# macOS/Linux
cp .env.example .env

Edit .env to customize settings (optional - defaults work out of the box).

Quick Start

Running the Server

python src/server.py

You should see output like:

============================================================
🚀 Playwright Automation Server v1.0.0
============================================================

📊 Inspector UI:    http://localhost:8000/inspector
📄 API Docs:        http://localhost:8000/docs
📋 OpenMCP:         http://localhost:8000/openmcp.json
🔌 MCP Endpoint:    http://localhost:8000/mcp

💡 Open http://localhost:8000/inspector in your browser
   to test all 6 browser automation tools interactively
   Press CTRL+C to stop the server

============================================================

Accessing the Inspector UI

What to do:

1. Copy the Inspector URL: http://localhost:8000/inspector
2. Paste it into your web browser (Chrome, Firefox, Edge, Safari, etc.)
3. The Inspector UI will open where you can test all tools

Note: If you see 0.0.0.0 in any URL, replace it with localhost in your browser.

The Inspector UI allows you to:

• See all available tools and their parameters
• Test tools interactively with a web form
• View real-time responses and errors
• Explore the OpenMCP metadata

How to use the Inspector:

1. You'll see a list of 6 tools (navigate, click_element, fill_input, etc.)
2. Click on a tool to see its description and parameters
3. Fill in the parameters (example: url = "https://example.com")
4. Click "Execute" to run the tool
5. View the results in the response panel

Testing with the Manual Test Script

python tests/manual_test.py

This runs a complete integration test suite covering all tools.

Usage Examples

Tool 1: Navigate

Navigate to a URL and wait for page load:

await navigate("https://example.com")
# Returns:
# {
#   "success": True,
#   "url": "https://example.com/",
#   "title": "Example Domain"
# }

Navigate with custom wait condition:

await navigate("https://example.com", wait_until="networkidle")

Wait conditions:

• "load" - Wait for the load event (default)
• "domcontentloaded" - Wait for DOMContentLoaded event
• "networkidle" - Wait until network is idle (no requests for 500ms)

Tool 2: Click Element

Click an element by CSS selector:

await click_element("button.submit")
# Returns:
# {
#   "success": True,
#   "selector": "button.submit",
#   "element_text": "Submit Form"
# }

Tool 3: Fill Input

Fill a form input with text:

await fill_input("input[name='email']", "user@example.com")
# Returns:
# {
#   "success": True,
#   "selector": "input[name='email']",
#   "text_length": 16
# }

Tool 4: Extract Text

Extract text content from an element:

await extract_text("h1")
# Returns:
# {
#   "success": True,
#   "selector": "h1",
#   "text": "Example Domain",
#   "text_length": 14
# }

Tool 5: Screenshot

Take a viewport screenshot:

await screenshot("./screenshots/homepage.png")
# Returns:
# {
#   "success": True,
#   "path": "C:\\Users\\David Jr\\playwright-mcp-server\\screenshots\\homepage.png",
#   "file_size": 52341,
#   "full_page": False,
#   "viewport": {"width": 1920, "height": 1080}
# }

Take a full-page screenshot:

await screenshot("./screenshots/full.png", full_page=True)

Supported formats: .png, .jpg, .jpeg

Tool 6: Get Page Info

Get current page information:

await get_page_info()
# Returns:
# {
#   "success": True,
#   "url": "https://example.com/",
#   "title": "Example Domain",
#   "viewport": {"width": 1920, "height": 1080}
# }

Configuration Reference

All configuration is done via environment variables in the .env file:

Server Configuration

Browser Configuration

Operation Timeouts

Screenshot Configuration

Error Handling

All tools return standardized error responses with actionable suggestions:

{
  "success": False,
  "error": "Element 'button.submit' not found or not clickable within 10000ms",
  "error_type": "ElementNotFound",
  "suggestion": "Check if selector is correct and element is visible",
  "selector": "button.submit"
}

Error Types

• ValidationError - Invalid inputs (bad URL, empty parameters, wrong types)
• ElementNotFound - Selector not found or element not visible/clickable
• TimeoutError - Operation exceeded timeout
• NetworkError - DNS failures, connection refused, SSL errors
• FileSystemError - File write permission errors
• InvalidElementState - Element is disabled or read-only
• UnknownError - Unexpected errors with details

Common Issues and Solutions

Browser fails to launch

Error: Failed to launch browser

Solution:

1. Ensure Playwright browsers are installed: playwright install chromium
2. Check that you have sufficient permissions
3. Try running with HEADLESS=false in .env to see browser window

Element not found

Error: Element not found with given selector

Solution:

1. Verify the CSS selector is correct
2. Check if element is inside an iframe (not currently supported)
3. Increase ELEMENT_TIMEOUT if page loads slowly
4. Use browser dev tools to test your selector

Navigation timeout

Error: Navigation timed out after 30000ms

Solution:

1. Increase NAVIGATION_TIMEOUT in .env
2. Check your internet connection
3. Verify the URL is accessible
4. Try using wait_until="domcontentloaded" instead of "load"

Screenshot permission denied

Error: Permission denied

Solution:

1. Check write permissions for the target directory
2. Ensure parent directories exist (created automatically by the tool)
3. Verify you have disk space available

Development

Project Structure

playwright-mcp-server/
├── src/
│   ├── __init__.py
│   ├── server.py          # Main MCP server with 6 tools
│   └── browser_manager.py # Singleton browser lifecycle management
├── tests/
│   ├── __init__.py
│   ├── test_server.py     # Unit tests
│   └── manual_test.py     # Integration test script
├── .env.example           # Environment template
├── .gitignore             # Git ignore rules
├── requirements.txt       # Python dependencies
├── README.md              # This file
└── pyproject.toml         # Project metadata

Running Tests

Unit tests (requires pytest):

pytest tests/test_server.py -v

Integration tests:

python tests/manual_test.py

Code Quality

This project follows best practices:

• ✅ Type hints on all functions
• ✅ Comprehensive docstrings
• ✅ Async/await throughout
• ✅ Singleton pattern for browser management
• ✅ Standardized error responses
• ✅ Configuration via environment variables
• ✅ Graceful shutdown handling

Architecture

BrowserManager (Singleton):

• Manages browser lifecycle
• Lazy initialization (browser starts on first use)
• Async lock prevents race conditions
• Automatic crash recovery
• Graceful cleanup on shutdown

MCP Server:

• Built with mcp-use framework
• 6 tools decorated with @server.tool()
• Streamable HTTP transport for Inspector UI
• Signal handlers for graceful shutdown
• Comprehensive error parsing

Integration with Claude Desktop

To use this server with Claude Desktop, add to your Claude config:

Windows: %APPDATA%\Claude\claude_desktop_config.json

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "playwright": {
      "command": "python",
      "args": [
        "C:\\Users\\David Jr\\playwright-mcp-server\\src\\server.py"
      ],
      "env": {
        "PYTHONPATH": "C:\\Users\\David Jr\\playwright-mcp-server\\src"
      }
    }
  }
}

Note: For production use with Claude Desktop, modify server.py to use transport="stdio" instead of transport="streamable-http".

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request

License

MIT License - feel free to use this in your own projects.

Support

For issues and questions:

• Check the Troubleshooting section above
• Review the test files for usage examples
• Open an issue on GitHub

Acknowledgments

Built with:

• Playwright - Browser automation framework
• mcp-use - Enhanced MCP server framework
• Model Context Protocol - Protocol specification

📚 Citation

@software{mcp_use2025, author = {Zullo, Pietro and Contributors}, title = {MCP-Use: Complete MCP Ecosystem for Python and TypeScript}, year = {2025}, publisher = {GitHub}, url = {https://github.com/mcp-use/mcp-use}

}

Version: 1.0.0 Author: Built with Claude Code Last Updated: 2026-01-30