🎭 Playwright

---

🔧 Custom Modifications (weidwonder's Fork)

This fork includes the following enhancements to the official Playwright MCP server:

✨ New Features

1. Enhanced Network Request Monitoring 🔍

Powerful network request monitoring for AI-powered web scraping and API analysis.

browser_network_requests (Enhanced)

• Added: Unique request IDs (req_0, req_1, etc.) for easy reference
• Added: Type filtering parameter
  • type: 'xhr' - Only XHR/Fetch requests (API calls)
  • type: 'all' - All requests including images, CSS, scripts (default)
• Usage:

  // Get only API calls
  await callTool({
    name: 'browser_network_requests',
    arguments: { type: 'xhr' }
  });
  // Output: [req_0] [POST] https://api.example.com/login => [200] OK

browser_network_request_detail (New)

Inspect complete request/response details by request ID.

• Location: packages/playwright/src/mcp/browser/tools/network.ts
• Functionality:
  • Request headers, body, and URL
  • Response headers, body (auto-formatted JSON), and status
  • Smart size limiting (>10KB bodies are omitted)
• Usage:

  await callTool({
    name: 'browser_network_request_detail',
    arguments: { id: 'req_0' }
  });

• Use Cases:
  • Analyze login flows for web scraping
  • Debug authentication issues
  • Reverse engineer API endpoints
  • Document API structures
• Tests: tests/mcp/network.spec.ts (4 passing tests)

Modified Files:

• packages/playwright/src/mcp/browser/tab.ts - Request ID tracking
• packages/playwright/src/mcp/browser/tools/network.ts - Enhanced tools
• See MCP_NETWORK_FEATURE_GUIDE.md for detailed documentation

2. browser_get_selector Tool

A new MCP tool that converts element references from page snapshots to standard CSS selectors or XPath expressions.

• Location: packages/playwright/src/mcp/browser/tools/selector.ts
• Functionality:
  • Input: Element ref from accessibility snapshot
  • Output: CSS selector and/or XPath
  • Supports dynamic JavaScript-rendered elements
• Usage:

  await callTool({
    name: 'browser_get_selector',
    arguments: {
      ref: 'e5',           // Element reference from snapshot
      type: 'both'         // 'css', 'xpath', or 'both'
    }
  });

• Dependencies: Uses playwright-dompath for accurate selector generation
• Tests: tests/mcp/selector.spec.ts (4 passing tests)

3. Browser Output Compression 🗜️

Optional intelligent compression of browser outputs to reduce context window usage by 40-70% using Claude Haiku 4.5.

• Added Parameter: compress_with_purpose (optional) to:

  • browser_navigate - Compress page snapshot after navigation
  • browser_snapshot - Compress current page snapshot
  • browser_tabs - Compress snapshot after tab operations

• Setup (Choose one option):

  Option 1: OAuth (Recommended) ⭐

  # 1. Install Claude Agent SDK (optional)
  npm install --save-optional @anthropic-ai/claude-agent-sdk
  
  # 2. Get OAuth token
  claude setup-token
  
  # 3. Set token in environment
  export CLAUDE_CODE_OAUTH_TOKEN='your-oauth-token'

  Option 2: AWS Bedrock

  # 1. Install AWS SDK (optional)
  npm install --save-optional @aws-sdk/client-bedrock-runtime
  
  # 2. Set credentials
  export AWS_BEARER_TOKEN_BEDROCK='your-token'

• Usage (⭐ Recommended):

  await callTool({
    name: 'browser_navigate',
    arguments: {
      url: 'https://example.com',
      compress_with_purpose: 'Preserve all main content'
    }
  });

• Key Points:

  • 🚀 Smart threshold: Content < 4k tokens is returned directly without compression
  • 🤖 Model: Uses Claude Haiku 4.5 (claude-haiku-4-5-20251001) for cost-effective compression
  • ✅ Use broad purposes like "Preserve all main content" for best results
  • ❌ Avoid specific purposes (e.g., "find login") - may filter important content
  • Automatically removes: ads, cookie banners, tracking scripts, newsletters
  • Preserves: main content, buttons, forms, element refs, pagination
  • Graceful fallback: OAuth → Bedrock → Original content

• Files:

  • packages/playwright/src/mcp/browser/compression.ts (compression module)
  • packages/playwright/src/mcp/browser/response.ts (async serialization)
  • See "Compression Feature" in Modified Files section below for complete file list

4. Snapshot Return Control 📸

Granular control over when page snapshots are returned after browser interactions to minimize token usage.

• Added Parameters to all interaction tools:
  • return_snapshot (boolean, optional, default: false) - Control whether to return page snapshot
  • compress_with_purpose (string, optional) - Compression purpose (only when return_snapshot=true)
• Affected Tools (12 total):
  • browser_click, browser_hover, browser_drag, browser_select_option
  • browser_mouse_click_xy, browser_mouse_drag_xy
  • browser_press_key, browser_type
  • browser_wait_for, browser_evaluate, browser_file_upload, browser_handle_dialog
• Benefits:
  • ⚡ Token Savings: Default behavior (return_snapshot: false) omits snapshots, saving 40-70% tokens
  • 🎯 Batch Operations: Perform multiple actions without snapshot overhead
  • 🗜️ Optional Compression: When snapshots are needed, compress them on-demand
• Usage:

  // Batch operations without snapshots
  await callTool({
    name: 'browser_click',
    arguments: { element: 'button', ref: 'e5', return_snapshot: false }
  });
  await callTool({
    name: 'browser_type',
    arguments: { element: 'input', ref: 'e8', text: 'hello', return_snapshot: false }
  });
  
  // Final check with compressed snapshot
  await callTool({
    name: 'browser_snapshot',
    arguments: { compress_with_purpose: 'Preserve all main content' }
  });
  
  // Or single action with compressed snapshot
  await callTool({
    name: 'browser_click',
    arguments: {
      element: 'submit',
      ref: 'e12',
      return_snapshot: true,
      compress_with_purpose: 'Preserve all main content'
    }
  });

• Files: See "Snapshot Control" in Modified Files section below

⚠️ Important Limitations

Single Connection Only: This MCP server does not support multiple concurrent connections. Only one AI agent can connect to the MCP server at a time. If you need multiple agents to access browser automation:

• Use separate MCP server instances (different ports/processes)
• Implement connection pooling/queuing in your application
• Use the official Playwright library directly for multi-agent scenarios

📁 Configuration Files

Two pre-configured setups for optimal MCP server performance:

• playwright-mcp-fast.json - Production configuration

  • Headless mode with aggressive optimizations
  • ~60-70% performance improvement
  • Ideal for automated workflows and CI/CD

• playwright-mcp-debug.json - Development configuration

  • Headed mode for visual debugging
  • Extended timeouts for troubleshooting
  • Minimal optimizations for maximum compatibility

Usage:

node packages/playwright/cli.js run-mcp-server --config playwright-mcp-fast.json

📝 Modified Files

Network Monitoring:

• packages/playwright/src/mcp/browser/tab.ts (request ID tracking)
• packages/playwright/src/mcp/browser/tools/network.ts (enhanced tools + new detail tool)
• tests/mcp/network.spec.ts (updated tests)
• MCP_NETWORK_FEATURE_GUIDE.md (comprehensive guide)

Selector Tool:

• packages/playwright/src/mcp/browser/tools/selector.ts (new)
• packages/playwright/src/mcp/browser/tools.ts (register new tool)
• tests/mcp/selector.spec.ts (new - 4 tests)
• tests/mcp/selector-simple-dynamic.spec.ts (new - dynamic element test)

Compression Feature:

• packages/playwright/src/mcp/browser/compression.ts (new - OAuth & Bedrock integration)
• packages/playwright/src/mcp/browser/compression.example.ts (new - usage example)
• packages/playwright/src/mcp/browser/response.ts (modified - async serialization)
• packages/playwright/src/mcp/browser/browserServerBackend.ts (modified - await serialize)
• packages/playwright/src/mcp/browser/tools/navigate.ts (modified - add compress parameter)
• packages/playwright/src/mcp/browser/tools/snapshot.ts (modified - add compress parameter)
• packages/playwright/src/mcp/browser/tools/tabs.ts (modified - add compress parameter)

Dependencies:

• package.json (added playwright-dompath)
• package-lock.json (dependency updates)
• Optional: @anthropic-ai/claude-agent-sdk (for OAuth compression, recommended)
• Optional: @aws-sdk/client-bedrock-runtime (for Bedrock compression)

Snapshot Control:

• packages/playwright/src/mcp/browser/tools/snapshot.ts (click, hover, drag, select_option)
• packages/playwright/src/mcp/browser/tools/mouse.ts (mouse_click_xy, mouse_drag_xy)
• packages/playwright/src/mcp/browser/tools/keyboard.ts (press_key, type)
• packages/playwright/src/mcp/browser/tools/wait.ts (wait_for)
• packages/playwright/src/mcp/browser/tools/evaluate.ts (evaluate)
• packages/playwright/src/mcp/browser/tools/files.ts (file_upload)
• packages/playwright/src/mcp/browser/tools/dialogs.ts (handle_dialog)

Configuration & Documentation:

• playwright-mcp-fast.json (production optimized config)
• playwright-mcp-debug.json (development debug config)
• README.md (this file - fork documentation)
• SNAPSHOT_CONTROL_SUMMARY.md (snapshot control feature documentation)

🚀 Quick Start with Modifications

Local Development Setup

# Clone your fork
git clone https://github.com/weidwonder/playwright.git
cd playwright

# Install dependencies (includes playwright-dompath)
npm ci

# Build the project
npm run build

# Install browsers
npx playwright install

# Run MCP server with fast configuration
node packages/playwright/cli.js run-mcp-server --config playwright-mcp-fast.json

# Run tests
npm run ctest-mcp -- tests/mcp/selector.spec.ts

Configuration for MCP Clients

Claude Desktop

Edit your Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "playwright-dev": {
      "command": "node",
      "args": [
        "<path-to-playwright-repo>/packages/playwright/cli.js",
        "run-mcp-server",
        "--config",
        "<path-to-playwright-repo>/playwright-mcp-fast.json"
      ],
      "env": {
        "NODE_PATH": "<path-to-playwright-repo>/node_modules"
      }
    }
  }
}

Replace <path-to-playwright-repo> with your actual path, for example:

• macOS/Linux: /Users/username/projects/playwright or ~/projects/playwright
• Windows: C:\Users\username\projects\playwright

Claude Code (CLI)

Add the MCP server using the Claude Code CLI:

# Navigate to your playwright repository
cd /path/to/playwright

# Add MCP server with fast configuration
claude mcp add --transport stdio playwright-dev \
  --env "NODE_PATH=$(pwd)/node_modules" \
  -- node "$(pwd)/packages/playwright/cli.js" run-mcp-server --config "$(pwd)/playwright-mcp-fast.json"

# Or for debug configuration (with visible browser)
claude mcp add --transport stdio playwright-debug \
  --env "NODE_PATH=$(pwd)/node_modules" \
  -- node "$(pwd)/packages/playwright/cli.js" run-mcp-server --config "$(pwd)/playwright-mcp-debug.json"

Other MCP Clients

For VS Code, Cline, Cursor, or other MCP clients, use similar configuration with:

• Command: node
• Args:
  • <path-to-repo>/packages/playwright/cli.js
  • run-mcp-server
  • --config
  • <path-to-repo>/playwright-mcp-fast.json
• Environment: NODE_PATH=<path-to-repo>/node_modules

Switching Between Configurations

Use playwright-mcp-fast.json for production (faster):

# ~60-70% faster, headless mode
node packages/playwright/cli.js run-mcp-server --config playwright-mcp-fast.json

Use playwright-mcp-debug.json for debugging (visible browser):

# Slower but you can see what's happening
node packages/playwright/cli.js run-mcp-server --config playwright-mcp-debug.json

🔗 Upstream

This fork is based on microsoft/playwright.

To sync with upstream:

git remote add upstream https://github.com/microsoft/playwright.git
git fetch upstream
git merge upstream/main

---

Documentation | API reference

Playwright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and WebKit with a single API. Playwright is built to enable cross-browser web automation that is ever-green, capable, reliable and fast.

	Linux	macOS	Windows
Chromium 142.0.7444.53	✅	✅	✅
WebKit 26.0	✅	✅	✅
Firefox 142.0.1	✅	✅	✅

Headless execution is supported for all browsers on all platforms. Check out system requirements for details.

Looking for Playwright for Python, .NET, or Java?

Installation

Playwright has its own test runner for end-to-end tests, we call it Playwright Test.

Using init command

The easiest way to get started with Playwright Test is to run the init command.

# Run from your project's root directory
npm init playwright@latest
# Or create a new project
npm init playwright@latest new-project

This will create a configuration file, optionally add examples, a GitHub Action workflow and a first test example.spec.ts. You can now jump directly to writing assertions section.

Manually

Add dependency and install browsers.

npm i -D @playwright/test
# install supported browsers
npx playwright install

You can optionally install only selected browsers, see install browsers for more details. Or you can install no browsers at all and use existing browser channels.

• Getting started
• API reference

Capabilities

Resilient • No flaky tests

Auto-wait. Playwright waits for elements to be actionable prior to performing actions. It also has a rich set of introspection events. The combination of the two eliminates the need for artificial timeouts - a primary cause of flaky tests.

Web-first assertions. Playwright assertions are created specifically for the dynamic web. Checks are automatically retried until the necessary conditions are met.

Tracing. Configure test retry strategy, capture execution trace, videos and screenshots to eliminate flakes.

No trade-offs • No limits

Browsers run web content belonging to different origins in different processes. Playwright is aligned with the architecture of the modern browsers and runs tests out-of-process. This makes Playwright free of the typical in-process test runner limitations.

Multiple everything. Test scenarios that span multiple tabs, multiple origins and multiple users. Create scenarios with different contexts for different users and run them against your server, all in one test.

Trusted events. Hover elements, interact with dynamic controls and produce trusted events. Playwright uses real browser input pipeline indistinguishable from the real user.

Test frames, pierce Shadow DOM. Playwright selectors pierce shadow DOM and allow entering frames seamlessly.

Full isolation • Fast execution

Browser contexts. Playwright creates a browser context for each test. Browser context is equivalent to a brand new browser profile. This delivers full test isolation with zero overhead. Creating a new browser context only takes a handful of milliseconds.

Log in once. Save the authentication state of the context and reuse it in all the tests. This bypasses repetitive log-in operations in each test, yet delivers full isolation of independent tests.

Powerful Tooling

Codegen. Generate tests by recording your actions. Save them into any language.

Playwright inspector. Inspect page, generate selectors, step through the test execution, see click points and explore execution logs.

Trace Viewer. Capture all the information to investigate the test failure. Playwright trace contains test execution screencast, live DOM snapshots, action explorer, test source and many more.

Looking for Playwright for TypeScript, JavaScript, Python, .NET, or Java?

Examples

To learn how to run these Playwright Test examples, check out our getting started docs.

Page screenshot

This code snippet navigates to Playwright homepage and saves a screenshot.

import { test } from '@playwright/test';

test('Page Screenshot', async ({ page }) => {
  await page.goto('https://playwright.dev/');
  await page.screenshot({ path: `example.png` });
});

Mobile and geolocation

This snippet emulates Mobile Safari on a device at given geolocation, navigates to maps.google.com, performs the action and takes a screenshot.

import { test, devices } from '@playwright/test';

test.use({
  ...devices['iPhone 13 Pro'],
  locale: 'en-US',
  geolocation: { longitude: 12.492507, latitude: 41.889938 },
  permissions: ['geolocation'],
})

test('Mobile and geolocation', async ({ page }) => {
  await page.goto('https://maps.google.com');
  await page.getByText('Your location').click();
  await page.waitForRequest(/.*preview\/pwa/);
  await page.screenshot({ path: 'colosseum-iphone.png' });
});

Evaluate in browser context

This code snippet navigates to example.com, and executes a script in the page context.

import { test } from '@playwright/test';

test('Evaluate in browser context', async ({ page }) => {
  await page.goto('https://www.example.com/');
  const dimensions = await page.evaluate(() => {
    return {
      width: document.documentElement.clientWidth,
      height: document.documentElement.clientHeight,
      deviceScaleFactor: window.devicePixelRatio
    }
  });
  console.log(dimensions);
});

Intercept network requests

This code snippet sets up request routing for a page to log all network requests.

import { test } from '@playwright/test';

test('Intercept network requests', async ({ page }) => {
  // Log and continue all network requests
  await page.route('**', route => {
    console.log(route.request().url());
    route.continue();
  });
  await page.goto('http://todomvc.com');
});

Resources

• Documentation
• API reference
• Contribution guide
• Changelog