Playwright MCP Server
A Model Context Protocol (MCP) server that provides comprehensive web automation tools via a remote Playwright/browserless instance. Features 10 powerful tools with Microsoft Playwright-standard naming convention.
Features
- 10 Comprehensive Web Automation Tools with Microsoft-standard naming
- Connect to any remote browserless/Playwright instance
- Advanced accessibility tree capture for LLM-friendly element identification
- File upload capabilities for testing forms and workflows
- Screenshot capture (full page or element-specific)
- HTML content extraction with flexible targeting
- Element interaction (clicking, typing, waiting)
- JavaScript execution with safety measures
- Page refresh with configurable wait conditions
- Comprehensive error handling and validation
Quick Start
1. Add to your AI assistant (No installation required)
Claude Code:
claude mcp add playwright-server -s user -- npx playwright-browserless-mcp --url ws://your-browserless-host:3000/playwright/chromium
Cursor AI:
cursor mcp add playwright-server -- npx playwright-browserless-mcp --url ws://your-browserless-host:3000/playwright/chromium
2. Restart your AI assistant and test
/mcp
Installation Options
Option 1: Use with npx (Recommended - No installation required)
npx playwright-browserless-mcp --url ws://your-browserless-host:3000/playwright/chromium
Option 2: Install globally
npm install -g playwright-browserless-mcp
playwright-browserless-mcp --url ws://your-browserless-host:3000/playwright/chromium
Option 3: Build from source
git clone https://github.com/b3nw/playwright-browserless-mcp.git
cd playwright-browserless-mcp
npm install && npm run build
Configuration
Required
--url: Your browserless WebSocket URL
Optional
--timeout: Request timeout in milliseconds (default: 30000)--width: Browser viewport width (default: 1920)--height: Browser viewport height (default: 1080)
Examples
# Basic usage
npx playwright-browserless-mcp --url ws://localhost:3000/playwright/chromium
# With custom settings
npx playwright-browserless-mcp --url ws://your-host:3000/playwright/chromium --timeout 60000 --width 1280 --height 720
# Using environment variable
PLAYWRIGHT_URL=ws://your-host:3000/playwright/chromium npx playwright-browserless-mcp
Setting Up Browserless
You need a running browserless/Playwright instance. Here are your options:
Option 1: Docker (Local)
docker run -p 3000:3000 ghcr.io/browserless/chromium
Then use: ws://localhost:3000/playwright/chromium
Option 2: Browserless Cloud
- Sign up at browserless.io
- Use your provided WebSocket URL
Option 3: Self-hosted
Follow the browserless documentation for self-hosting.
AI Assistant Integration
Claude Code
Method 1: CLI (Recommended)
claude mcp add playwright-server -s user -- npx playwright-browserless-mcp --url ws://your-browserless-host:3000/playwright/chromium
Method 2: Manual config file
Edit ~/.config/claude/claude_desktop_config.json:
{
"mcpServers": {
"playwright-server": {
"type": "stdio",
"command": "npx",
"args": ["playwright-browserless-mcp", "--url", "ws://your-browserless-host:3000/playwright/chromium"]
}
}
}
Cursor AI
Method 1: CLI
cursor mcp add playwright-server -- npx playwright-browserless-mcp --url ws://your-browserless-host:3000/playwright/chromium
Method 2: Settings UI
- Open Cursor preferences (
Cmd/Ctrl + ,) - Navigate to "Features" → "Model Context Protocol"
- Click "Add MCP Server"
- Configure:
- Name:
playwright-server - Command:
npx - Args:
["playwright-browserless-mcp", "--url", "ws://your-browserless-host:3000/playwright/chromium"]
- Name:
VS Code with Claude Extension
Edit your Claude configuration to include:
{
"mcpServers": {
"playwright-server": {
"type": "stdio",
"command": "npx",
"args": ["playwright-browserless-mcp", "--url", "ws://your-browserless-host:3000/playwright/chromium"]
}
}
}
Available MCP Tools (v1.1.0)
Core Navigation & Interaction
browser_navigate
Navigate to a URL and wait for page load.
url(required): URL to navigate towaitUntil(optional): "networkidle", "domcontentloaded", or "load"
browser_click
Click on an element specified by CSS selector.
selector(required): CSS selector for element to click
browser_type
Type text into an input field.
selector(required): CSS selector for input elementtext(required): Text to type
browser_wait_for
Wait for an element to appear on the page.
selector(required): CSS selector for elementtimeout(optional): Timeout in milliseconds (default: 30000)
Content Extraction & Analysis
browser_take_screenshot
Take a screenshot of the current page or specific element.
fullPage(optional): Take full page screenshot (default: false)selector(optional): CSS selector for specific element
browser_get_html
Extract HTML content from the page or specific element.
selector(optional): CSS selector for specific element
browser_snapshot 🆕
Get accessibility tree snapshot for LLM-friendly element identification. Perfect for understanding page structure and finding elements semantically.
selector(optional): CSS selector to limit snapshot to specific element- Returns: Structured accessibility data with roles, names, and selectors
Advanced Features
browser_file_upload 🆕
Upload files to file input elements. Essential for testing file upload forms and workflows.
selector(required): CSS selector for file input elementpaths(required): Array of file paths to upload
browser_refresh 🆕
Refresh the current page with configurable wait conditions.
waitUntil(optional): "networkidle", "domcontentloaded", or "load" (default: "load")timeout(optional): Custom timeout in milliseconds
browser_evaluate
Execute JavaScript code in the browser context with safety measures.
script(required): JavaScript code to execute
Example Usage
Once configured, you can use these tools in your AI assistant:
Basic Navigation
Please navigate to https://example.com and take a screenshot
Form Interaction
Fill out the form on this page with name "John Doe" and email "john@example.com", then upload the resume.pdf file
Advanced Analysis
Get an accessibility snapshot of this page to understand its structure, then click the submit button and wait for the success message
Testing Workflows
Navigate to the login page, fill in credentials, upload a profile picture, and verify the account was created successfully
What's New in v1.1.0
- 🔄 Microsoft Playwright Standard Naming: All tools now use
browser_prefix for consistency - 🆕 Accessibility Tree Snapshots:
browser_snapshottool for semantic element identification - 📁 File Upload Support:
browser_file_uploadtool for testing file forms - 🔄 Page Refresh:
browser_refreshtool with configurable wait conditions - ✅ 10 Total Tools: Expanded from 7 to 10 comprehensive automation tools
- 🎯 Enhanced Testing: Better support for complex web application testing workflows
Troubleshooting
Server not appearing in /mcp
- Restart your AI assistant completely
- Verify the server works:
npx playwright-browserless-mcp --help - Check the configuration syntax in your config file
Connection errors
- Verify your browserless instance is running
- Test the WebSocket URL in a browser
- Check firewall/network settings
Tool naming issues
If you see old tool names (navigate, screenshot, etc.), you're using an outdated version. Update to v1.1.0:
npx playwright-browserless-mcp@latest --url your-browserless-url
Version compatibility
This server works with Playwright v1.53. If your browserless instance uses a different version, you may need to adjust the playwright dependency.
License
MIT