Skip to main content
Glama

Playwright MCP Server

by b3nw
README.md8.29 kB
# 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:** ```bash claude mcp add playwright-server -s user -- npx playwright-browserless-mcp --url ws://your-browserless-host:3000/playwright/chromium ``` **Cursor AI:** ```bash 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) ```bash npx playwright-browserless-mcp --url ws://your-browserless-host:3000/playwright/chromium ``` ### Option 2: Install globally ```bash npm install -g playwright-browserless-mcp playwright-browserless-mcp --url ws://your-browserless-host:3000/playwright/chromium ``` ### Option 3: Build from source ```bash 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 ```bash # 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) ```bash docker run -p 3000:3000 ghcr.io/browserless/chromium ``` Then use: `ws://localhost:3000/playwright/chromium` ### Option 2: Browserless Cloud 1. Sign up at [browserless.io](https://browserless.io) 2. Use your provided WebSocket URL ### Option 3: Self-hosted Follow the [browserless documentation](https://docs.browserless.io) for self-hosting. ## AI Assistant Integration ### Claude Code **Method 1: CLI (Recommended)** ```bash 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`: ```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** ```bash cursor mcp add playwright-server -- npx playwright-browserless-mcp --url ws://your-browserless-host:3000/playwright/chromium ``` **Method 2: Settings UI** 1. Open Cursor preferences (`Cmd/Ctrl + ,`) 2. Navigate to "Features" → "Model Context Protocol" 3. Click "Add MCP Server" 4. Configure: - **Name**: `playwright-server` - **Command**: `npx` - **Args**: `["playwright-browserless-mcp", "--url", "ws://your-browserless-host:3000/playwright/chromium"]` ### VS Code with Claude Extension Edit your Claude configuration to include: ```json { "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 to - `waitUntil` (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 element - `text` (required): Text to type #### `browser_wait_for` Wait for an element to appear on the page. - `selector` (required): CSS selector for element - `timeout` (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 element - `paths` (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_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` 1. Restart your AI assistant completely 2. Verify the server works: `npx playwright-browserless-mcp --help` 3. Check the configuration syntax in your config file ### Connection errors 1. Verify your browserless instance is running 2. Test the WebSocket URL in a browser 3. 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: ```bash 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

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/b3nw/playwright-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server