Provides a way to run a browserless/Playwright instance locally using Docker for web automation tasks
Allows fetching the MCP server directly from GitHub repository using npx, enabling web automation without local installation
Enables execution of JavaScript code in browser context, allowing custom scripting for web automation tasks
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:
Cursor AI:
2. Restart your AI assistant and test
Installation Options
Option 1: Use with npx (Recommended - No installation required)
Option 2: Install globally
Option 3: Build from source
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
Setting Up Browserless
You need a running browserless/Playwright instance. Here are your options:
Option 1: Docker (Local)
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)
Method 2: Manual config file
Edit ~/.config/claude/claude_desktop_config.json
:
Cursor AI
Method 1: CLI
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:
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
Form Interaction
Advanced Analysis
Testing Workflows
What's New in v1.1.0
- 🔄 Microsoft Playwright Standard Naming: All tools now use
browser_
prefix for consistency - 🆕 Accessibility Tree Snapshots:
browser_snapshot
tool for semantic element identification - 📁 File Upload Support:
browser_file_upload
tool for testing file forms - 🔄 Page Refresh:
browser_refresh
tool 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:
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
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
Tools
A Model Context Protocol server that enables AI assistants to perform web automation tasks by connecting to remote Playwright/browserless instances, supporting navigation, screenshots, HTML extraction, and element interaction.
Related MCP Servers
- -securityAlicense-qualityA Model Context Protocol server that provides browser automation capabilities using Playwright, enabling LLMs to interact with web pages, take screenshots, and execute JavaScript in a real browser environment.Last updated -14PythonApache 2.0
- AsecurityAlicenseAqualityA Model Context Protocol server that provides browser automation capabilities using Playwright, enabling LLMs to interact with web pages, take screenshots, generate test code, scrape web content, and execute JavaScript in real browser environments.Last updated -3110,680TypeScriptMIT License
- AsecurityFlicenseAqualityA Model Context Protocol server that enables AI assistants to interact with web browsers through Playwright, providing automation capabilities for navigation, interaction, and screenshots.Last updated -143JavaScript
- AsecurityFlicenseAqualityA Model Context Protocol server that provides browser automation capabilities using Playwright, enabling AI assistants to interact with web pages through a standardized interface.Last updated -143JavaScript