# 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**
```bash
cd "C:\Users\David Jr\playwright-mcp-server"
```
2. **Create a virtual environment**
```bash
python -m venv venv
```
3. **Activate the virtual environment**
Windows:
```bash
venv\Scripts\activate
```
macOS/Linux:
```bash
source venv/bin/activate
```
4. **Install dependencies**
```bash
pip install -r requirements.txt
```
5. **Install Playwright browsers**
```bash
playwright install chromium
```
6. **Configure environment variables**
```bash
# 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
```bash
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
```bash
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:
```python
await navigate("https://example.com")
# Returns:
# {
# "success": True,
# "url": "https://example.com/",
# "title": "Example Domain"
# }
```
Navigate with custom wait condition:
```python
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:
```python
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:
```python
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:
```python
await extract_text("h1")
# Returns:
# {
# "success": True,
# "selector": "h1",
# "text": "Example Domain",
# "text_length": 14
# }
```
### Tool 5: Screenshot
Take a viewport screenshot:
```python
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:
```python
await screenshot("./screenshots/full.png", full_page=True)
```
**Supported formats:** `.png`, `.jpg`, `.jpeg`
### Tool 6: Get Page Info
Get current page information:
```python
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
| Variable | Description | Default |
|----------|-------------|---------|
| `DEBUG` | Enable debug mode with enhanced logging | `true` |
| `HOST` | Server host address | `0.0.0.0` |
| `PORT` | Server port | `8000` |
### Browser Configuration
| Variable | Description | Default |
|----------|-------------|---------|
| `HEADLESS` | Run browser in headless mode | `true` |
| `BROWSER_TIMEOUT` | Browser launch timeout (ms) | `30000` |
| `VIEWPORT_WIDTH` | Browser viewport width | `1920` |
| `VIEWPORT_HEIGHT` | Browser viewport height | `1080` |
### Operation Timeouts
| Variable | Description | Default |
|----------|-------------|---------|
| `NAVIGATION_TIMEOUT` | Page navigation timeout (ms) | `30000` |
| `ELEMENT_TIMEOUT` | Element interaction timeout (ms) | `10000` |
| `SCREENSHOT_TIMEOUT` | Screenshot capture timeout (ms) | `5000` |
### Screenshot Configuration
| Variable | Description | Default |
|----------|-------------|---------|
| `SCREENSHOT_DIR` | Directory for screenshots | `./screenshots` |
## Error Handling
All tools return standardized error responses with actionable suggestions:
```python
{
"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):
```bash
pytest tests/test_server.py -v
```
**Integration tests**:
```bash
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`
```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](https://playwright.dev/) - Browser automation framework
- [mcp-use](https://github.com/modelcontextprotocol/mcp-use) - Enhanced MCP server framework
- [Model Context Protocol](https://modelcontextprotocol.io/) - 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
