Playwright Stealth

Playwright Stealth MCP Server

A Model Context Protocol (MCP) server for browser automation using Playwright with optional stealth mode to bypass anti-bot protection.

Features

• Simplified API: Single browser_execute tool that exposes the full Playwright API instead of many specialized tools
• Stealth Mode: Optional anti-detection measures using playwright-extra and puppeteer-extra-plugin-stealth
• Persistent Sessions: Browser session persists across tool calls for multi-step automation
• Screenshot Support: Capture page screenshots for visual verification
• Video Recording: Record browser interactions as WebM videos with explicit start/stop controls
• Code Execution: Run arbitrary Playwright code with access to the page object
• Full Permissions: All browser permissions (notifications, geolocation, camera, etc.) granted by default for testing web apps

Installation

npx playwright-stealth-mcp-server

Or install globally:

npm install -g playwright-stealth-mcp-server

Configuration

Claude Desktop Configuration

Add to your Claude Desktop config file:

Non-Stealth Mode (Standard Playwright):

{

"mcpServers": { "playwright": { "command": "npx", "args": ["-y", "playwright-stealth-mcp-server"], "env": { "STEALTH_MODE": "false" } } } }

Stealth Mode (Anti-bot bypass):

{

"mcpServers": { "playwright-stealth": { "command": "npx", "args": ["-y", "playwright-stealth-mcp-server"], "env": { "STEALTH_MODE": "true" } } } }

With Proxy (e.g., BrightData Residential Proxy):

{

"mcpServers": { "playwright-proxy": { "command": "npx", "args": ["-y", "playwright-stealth-mcp-server"], "env": { "STEALTH_MODE": "true", "PROXY_URL": "http://brd.superproxy.io:22225", "PROXY_USERNAME": "brd-customer-XXXXX-zone-residential", "PROXY_PASSWORD": "your-password" } } } }

Environment Variables

Available Tools

browser_execute

Execute Playwright code with access to the page object.

Parameters:

• code (required): JavaScript code to execute. The page object is available in scope.
• timeout (optional): Execution timeout in milliseconds.

Example:

await page.goto('https://example.com');

const title = await page.title(); return title;

browser_screenshot

Take a screenshot of the current page, a specific element, or a page region. Screenshots are saved to filesystem storage and can be accessed later via MCP resources.

Parameters:

• fullPage (optional): Capture full scrollable page. Default: false
• selector (optional): CSS selector of a specific element to screenshot (e.g., #main-content, .hero-banner, table.results)
• clip (optional): Region of the page to screenshot as {x, y, width, height} in pixels
• resultHandling (optional): How to handle the result:
• saveAndReturn (default): Saves to storage AND returns inline base64 image
• saveOnly: Saves to storage and returns only the resource URI (more efficient for large screenshots)

Note: fullPage, selector, and clip are mutually exclusive. Only one can be specified per call.

Returns:

• With saveAndReturn: Inline base64 PNG image plus a resource_link with the file URI
• With saveOnly: Only a resource_link with the file:// URI to the saved screenshot

browser_get_state

Get the current browser state including URL, title, and configuration.

browser_close

Close the browser session. A new browser will be launched on the next browser_execute call.

browser_start_recording

Start recording the browser session as a WebM video.

This tool recycles the browser context with video recording enabled. Session state (cookies, localStorage, sessionStorage) is automatically preserved across the context recycling.

If called while already recording, the current recording is automatically stopped and saved before starting a new one.

browser_stop_recording

Stop recording and save the video.

Returns a resource_link with the file:// URI to the saved video (WebM format). Session state is preserved — the browser navigates back to the previous URL automatically.

Returns an error if no recording is active.

MCP Resources

The server exposes saved screenshots and video recordings as MCP resources. Clients can use:

• resources/list: List all saved screenshots and videos with their URIs and metadata
• resources/read: Read a screenshot or video by its file:// URI

This allows clients to access previously captured screenshots and recordings without needing to take new ones.

Usage Examples

Navigate and Extract Data

// Navigate to a page

await page.goto('https://news.ycombinator.com');

// Extract headlines const headlines = await page.$$eval('.titleline > a', (links) => links.slice(0, 5).map((a) => a.textContent) );

return headlines;

Fill and Submit a Form

await page.goto('https://example.com/login');

// Fill credentials await page.fill('input[name="email"]', 'user@example.com'); await page.fill('input[name="password"]', 'password123');

// Submit form await page.click('button[type="submit"]');

// Wait for navigation await page.waitForNavigation();

return await page.title();

Handle Dynamic Content

await page.goto('https://spa-example.com');

// Wait for element to appear await page.waitForSelector('.loaded-content');

// Click to load more await page.click('.load-more-button');

// Wait for new content await page.waitForSelector('.new-items');

const items = await page.$$eval('.item', (els) => els.map((el) => el.textContent)); return items;

Security Considerations

Important: The browser_execute tool executes arbitrary JavaScript code. This design provides full Playwright API access but has security implications:

• Only use this server with trusted input (e.g., from an LLM in a controlled environment)
• The code runs in a Node.js context with access to the page object
• Do not expose this server to untrusted users or public networks

This is intentional for maximum flexibility - it allows LLMs to leverage their existing Playwright knowledge. For production use, ensure proper access controls are in place.

When to Use Stealth Mode

Enable stealth mode (STEALTH_MODE=true) when:

• Accessing sites with Cloudflare protection
• Sites that block automation tools
• Pages that detect headless browsers
• OAuth flows that trigger CAPTCHA challenges

Stealth mode includes:

• WebDriver property masking
• Chrome automation flag removal
• User-Agent normalization
• Plugin/mime type spoofing
• Navigator property patching

Fingerprint Configuration

When running in Docker/Linux environments, bot detection systems may identify a fingerprint mismatch between the User-Agent header and other browser signals like navigator.platform. Use these environment variables to configure consistent fingerprints:

Example: macOS Fingerprint (for Docker/Linux)

{

"mcpServers": { "playwright-stealth": { "command": "npx", "args": ["-y", "playwright-stealth-mcp-server"], "env": { "STEALTH_MODE": "true", "STEALTH_USER_AGENT": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36", "STEALTH_MASK_LINUX": "false" } } } }

Why this matters:

• By default, stealth mode masks Linux as Windows in the User-Agent header only
• However, navigator.platform still reports the actual OS (e.g., "Linux x86_64")
• This mismatch between User-Agent and platform triggers bot detection
• Setting STEALTH_MASK_LINUX=false disables this masking, allowing the real platform to show
• Combined with a custom STEALTH_USER_AGENT, you can present a consistent fingerprint

When to Use Proxy

Configure proxy settings when:

• Scraping sites that rate-limit by IP address
• Accessing geo-restricted content
• Avoiding IP-based blocks or bans
• Rotating IPs for large-scale data collection

The server supports HTTP/HTTPS proxies with optional authentication, making it compatible with:

• BrightData (Residential, Datacenter, ISP proxies)
• Oxylabs, Smartproxy, and other residential proxy providers
• Self-hosted proxy servers
• Corporate HTTP proxies

Note: When proxy is configured, the server performs a health check on startup to verify the proxy connection works. If the health check fails, the server will exit with an error.

HTTPS Certificate Errors

By default, the server ignores HTTPS certificate errors (IGNORE_HTTPS_ERRORS=true). This is convenient for common automation scenarios:

• Docker environments where SSL certificates may not match hostnames
• Corporate networks with MITM proxies that re-sign certificates
• Self-signed certificates in development or staging environments
• Residential proxies that perform HTTPS inspection

To enable strict certificate validation, set IGNORE_HTTPS_ERRORS=false:

{

"mcpServers": { "playwright": { "command": "npx", "args": ["-y", "playwright-stealth-mcp-server"], "env": { "IGNORE_HTTPS_ERRORS": "false" } } } }

Security Note: For production environments where certificate validation is important, se