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"]

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)

`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:

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`

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

Install Server

HTTP connection URL

security – no known vulnerabilities

license - not found

quality - confirmed to work

How are these scores calculated?

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

View all 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

Puppeteer MCP Server
twolven
-
security
A
license
-
quality
A 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 -
14
Python
Apache 2.0
Playwright MCP Server
BhanuTJ93
A
security
A
license
A
quality
A 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 -
31
10,680
TypeScript
MIT License
MCP Browser Server
Wladastic
A
security
F
license
A
quality
A 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 -
14
3
JavaScript
AutoProbeMCP
Wladastic
A
security
F
license
A
quality
A 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 -
14
3
JavaScript

View all related MCP servers