tontoko/fast-playwright-mcp

Fast Playwright MCP

This MCP server is a fork of the Microsoft one.

A Model Context Protocol (MCP) server that provides browser automation capabilities using Playwright. This server enables LLMs to interact with web pages through structured accessibility snapshots, bypassing the need for screenshots or visually-tuned models.

Key Features

• Fast and lightweight. Uses Playwright’s accessibility tree, not pixel-based input.
• LLM-friendly. No vision models needed, operates purely on structured data.
• Deterministic tool application. Avoids ambiguity common with screenshot-based approaches.

Fast Server Features (This Fork)

• Token Optimization. All tools support an expectation parameter to control response content:
  • includeCode: false - Suppress Playwright code generation to reduce tokens
  • includeSnapshot: false - Skip page snapshot for minimal responses (70-80% token reduction)
  • includeConsole: false - Exclude console messages
  • includeTabs: false - Hide tab information
• Image Compression. Screenshot tool supports imageOptions:
  • format: 'jpeg' - Use JPEG instead of PNG
  • quality: 1-100 - Compress images (e.g., 50 for 50% quality)
  • maxWidth: number - Resize images to max width
• Batch Execution. Use browser_batch_execute for multiple operations:
  • Significant token reduction by eliminating redundant responses
  • Per-step and global expectation configuration
  • Error handling with continueOnError and stopOnFirstError options
• Snapshot Control. Limit snapshot size with snapshotOptions:
  • selector: string - Capture only specific page sections (recommended over maxLength)
  • format: "aria" - Accessibility tree format for LLM processing
• Diff Detection. Track only changes with diffOptions:
  • enabled: true - Show only what changed from previous state (massive token saver)
  • format: "minimal" - Ultra-compact diff output
  • Perfect for monitoring state changes during navigation or interactions
• Diagnostic System. Advanced debugging and element discovery tools:
  • browser_find_elements - Find elements using multiple search criteria (text, role, attributes)
  • browser_diagnose - Comprehensive page analysis with performance metrics and troubleshooting
  • Enhanced error handling with alternative element suggestions
  • Page structure analysis (iframes, modals, accessibility metrics)
  • Performance monitoring with execution time under 300ms
• Enhanced Selector System. Unified element selection with multiple strategies:
  • Selector Arrays: All element-based tools now support multiple selectors with automatic fallback
  • 4 Selector Types:
    • ref: System-generated element IDs from previous tool results (highest priority)
    • role: ARIA roles with optional text matching (e.g., {role: "button", text: "Submit"})
    • css: Standard CSS selectors (e.g., {css: "#submit-btn"})
    • text: Text content search with optional tag filtering (e.g., {text: "Click me", tag: "button"})
  • Intelligent Resolution: Parallel CSS resolution, sequential role matching, automatic fallback
  • Multiple Match Handling: When multiple elements match, returns candidate list for LLM selection
  • HTML Inspection: New browser_inspect_html tool for intelligent content extraction with depth control

Adaptive tool catalog

Version 0.2 defaults to an adaptive seven-tool startup catalog, reducing the fixed MCP context cost while preserving access to all registered tools.

• browser_tools searches, enables, disables, resets, and reports catalog state.
• browser_query dispatches schema-validated read-only tools.
• browser_execute dispatches schema-validated action and destructive tools.
• Known hidden tools remain directly callable for existing integrations.
• --tool-profile=full restores the previous complete static catalog.
• --tool-profile=minimal exposes only the discovery and dispatch gateways.

The repository enforces a serialized startup budget in CI. Run bun run benchmark:tools -- --check to inspect the current profile sizes.

Security and interoperability controls

The CLI and configuration file support CDP headers and connection timeout, HTTP Host allowlisting, output-directory size limits, response secret redaction, action/navigation/expectation timeouts, a custom test-id attribute, and codegen: "none". The optional offline MCP Apps dashboard is enabled with --caps=apps.

Maintenance documentation:

• Architecture
• 0.2 migration guide
• Upstream compatibility policy
• Upstream compatibility matrix
• Release checklist

Requirements

• Node.js 20 or newer
• VS Code, Cursor, Windsurf, Claude Desktop, Goose or any other MCP client

Getting started

First, install the Playwright MCP server with your client.

Standard config works in most of the tools:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@tontoko/fast-playwright-mcp@latest"
      ]
    }
  }
}

Configuration file

The Playwright MCP server can be configured using a JSON file. You can specify the configuration file using the --config command line option:

npx @tontoko/fast-playwright-mcp@latest --config path/to/config.json

User profile

You can run Playwright MCP with a persistent profile, like a regular browser (default), in isolated contexts for testing sessions, or connect to an existing browser using the browser extension.

Persistent profile

All the logged in information will be stored in the persistent profile, you can delete it between sessions if you’d like to clear the offline state. The persistent profile will be located in the following directories and you can override it with the --user-data-dir argument.

# Windows
%USERPROFILE%\AppData\Local\ms-playwright\mcp-{channel}-profile

# macOS
- ~/Library/Caches/ms-playwright/mcp-{channel}-profile

# Linux
- ~/.cache/ms-playwright/mcp-{channel}-profile

Isolated

In isolated mode, each session is started in an isolated profile. Every time you ask MCP to close the browser, the session is closed and all the storage state for this session is lost. Isolated mode can be used for testing purposes to ensure each session is independent.

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@tontoko/fast-playwright-mcp@latest",
        "--isolated"
      ]
    }
  }
}

Browser extension

The Playwright MCP Browser Extension allows you to connect to existing browser tabs and leverage your current browser session and authenticated state. See the extension/README.md for installation and usage instructions.

Configuration

Playwright MCP server supports following arguments. All of them are optional:

> npx @tontoko/fast-playwright-mcp@latest --help
  --allowed-hosts           comma-separated list of allowed HTTP Host
                                   header values
  --allowed-origins       semicolon-separated list of origins to allow
                                   the browser to request. Default is to allow
                                   all.
  --blocked-origins       semicolon-separated list of origins to block
                                   the browser from requesting. Blocklist is
                                   evaluated before allowlist.
  --block-service-workers          block service workers
  --browser               browser or chrome channel to use: chrome,
                                   firefox, webkit, or msedge
  --caps                     comma-separated optional capabilities:
                                   vision, pdf, apps
  --cdp-endpoint         CDP endpoint to connect to
  --cdp-header          CDP request header in Name: Value form; may
                                   be repeated
  --cdp-timeout           CDP connection timeout in milliseconds
  --codegen                  generated code mode: typescript or none
  --config                   path to the configuration file
  --device                 device to emulate, for example: "iPhone 15"
  --executable-path          path to the browser executable
  --headless                       run browser in headless mode, headed by
                                   default
  --host                     host to bind server to. Default is localhost.
                                   Use 0.0.0.0 to bind all interfaces.
  --ignore-https-errors            ignore HTTPS errors
  --isolated                       use an in-memory isolated browser profile
  --image-responses          whether image responses are allow or omit
  --no-sandbox                     disable the Chromium sandbox for process
                                   types that normally use it
  --output-dir               directory for output files
  --output-max-size         maximum output directory size in bytes; zero
                                   disables eviction
  --port                     port to listen on for HTTP transport
  --proxy-bypass           comma-separated domains to bypass the proxy
  --proxy-server            proxy server URL
  --save-session                   save the Playwright MCP session
  --save-trace                     save the Playwright trace
  --secrets                  dotenv file containing values to redact
  --storage-state            path to storage state for isolated sessions
  --test-id-attribute   attribute used by test-id selectors
  --timeout-action        default action timeout in milliseconds
  --timeout-expect        default expectation timeout in milliseconds
  --timeout-navigation    default navigation timeout in milliseconds
  --timeout-settle        delay after browser actions before capturing
                                   the response, in milliseconds
  --tool-profile          tool catalog profile: adaptive, full, or
                                   minimal
  --user-agent          browser user-agent string
  --user-data-dir            browser user data directory
  --viewport-size            viewport size as width,height, for example
                                   1280,720

Custom Browser Executables (Firefox Forks and Chrome/Chromium Forks)

By default, Playwright launches its bundled browsers. You can use a custom browser executable (for example a branded Chromium fork or a Firefox-based browser) by specifying the full path to the executable. See CUSTOM_BROWSER_EXECUTABLES.md for detailed, platform-specific instructions and warnings.

• CLI: --browser with --executable-path
• Config file: set browser.launchOptions.executablePath

Examples:

npx @tontoko/fast-playwright-mcp@latest --browser chromium --executable-path "/opt/google/chrome/chrome"

npx @tontoko/fast-playwright-mcp@latest --browser firefox --executable-path "/opt/waterfox/waterfox"

Important: third-party browser compatibility is not guaranteed. Verify the publisher and binary before use; the server executes the supplied path directly. Waterfox is only an illustrative Firefox-family example and may not support Playwright’s required Firefox protocol patches.

Standalone MCP server

When running headed browser on system w/o display or from worker processes of the IDEs, run the MCP server from environment with the DISPLAY set to a valid X server. For example DISPLAY=:1 npx @tontoko/fast-playwright-mcp@latest --port 8931.

Docker

NOTE: The Docker implementation only supports headless chromium at the moment.

{
  "mcpServers": {
    "playwright": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "--init", "--pull=always", "mcr.microsoft.com/playwright/mcp"]
    }
  }
}

Or if you prefer to run the container as a long-lived service instead of letting the MCP client spawn it, use:

docker run -d -i --rm --init --pull=always \
  --entrypoint node \
  --name playwright-mcp \
  -p 8931:8931 \
  mcr.microsoft.com/playwright/mcp \
  cli.js --headless --browser chromium --no-sandbox --port 8931

The server will be available at port 8931 and can be accessed via any MCP client.

You can build the Docker image yourself.

docker build -t mcr.microsoft.com/playwright/mcp .

Programmatic usage

import http from 'node:http';

import { createConnection } from '@tontoko/fast-playwright-mcp';
import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';

http.createServer(async (req, res) => {
  // ...

  // Creates a headless Playwright MCP server with SSE transport
  const connection = await createConnection({ browser: { launchOptions: { headless: true } } });
  const transport = new SSEServerTransport('/messages', res);
  await connection.connect(transport);
  // ...
});

Tools

Token Optimization Examples

The Fast Server provides advanced token optimization through expectation controls and batch execution:

Basic Expectation Control

{
  "name": "browser_navigate",
  "arguments": {
    "url": "https://example.com",
    "expectation": {
      "includeSnapshot": false,
      "includeConsole": false,
      "includeTabs": false
    }
  }
}

Expectation Options

• includeSnapshot (boolean, default: varies by tool): Include page accessibility snapshot
• includeConsole (boolean, default: varies by tool): Include browser console messages
• includeDownloads (boolean, default: true): Include download information
• includeTabs (boolean, default: varies by tool): Include tab information
• includeCode (boolean, default: true): Include executed code in response

Advanced Snapshot Options

{
  "name": "browser_click",
  "arguments": {
    "element": "Login button",
    "ref": "#login-btn",
    "expectation": {
      "includeSnapshot": true,
      "snapshotOptions": {
        "selector": ".dashboard",
        "maxLength": 1000,
        "format": "text"
      }
    }
  }
}

Console Filtering Options

{
  "name": "browser_navigate",
  "arguments": {
    "url": "https://example.com",
    "expectation": {
      "includeConsole": true,
      "consoleOptions": {
        "levels": ["error", "warn"],
        "maxMessages": 5,
        "patterns": ["^Error:"],
        "removeDuplicates": true
      }
    }
  }
}

Batch Execution

Execute multiple browser actions in a single request with optimized response handling and flexible error control.

Basic Batch Execution

{
  "name": "browser_batch_execute",
  "arguments": {
    "steps": [
      {
        "tool": "browser_navigate",
        "arguments": { "url": "https://example.com/login" }
      },
      {
        "tool": "browser_type",
        "arguments": { 
          "element": "username field", 
          "ref": "#username", 
          "text": "testuser" 
        }
      },
      {
        "tool": "browser_type",
        "arguments": { 
          "element": "password field", 
          "ref": "#password", 
          "text": "password" 
        }
      },
      {
        "tool": "browser_click",
        "arguments": { "element": "login button", "ref": "#login-btn" }
      }
    ]
  }
}

Advanced Batch Configuration

{
  "name": "browser_batch_execute",
  "arguments": {
    "steps": [
      {
        "tool": "browser_navigate",
        "arguments": { "url": "https://example.com" },
        "expectation": { "includeSnapshot": false },
        "continueOnError": true
      },
      {
        "tool": "browser_click",
        "arguments": { "element": "button", "ref": "#submit" },
        "expectation": { 
          "includeSnapshot": true,
          "snapshotOptions": { "selector": ".result-area" }
        }
      }
    ],
    "stopOnFirstError": false,
    "globalExpectation": {
      "includeConsole": false,
      "includeTabs": false
    }
  }
}

Error Handling Options

• continueOnError (per step): Continue batch execution even if this step fails
• stopOnFirstError (global): Stop entire batch on first error
• Flexible combination allows for robust automation workflows

Tool-Specific Defaults

Each tool has optimized defaults based on typical usage patterns:

• Navigation tools (browser_navigate): Include full context for verification
• Interactive tools (browser_click, browser_type): Include snapshot but minimal logging
• Screenshot/snapshot tools: Exclude additional context
• Code evaluation: Include console output but minimal other info
• Wait operations: Minimal output for efficiency

Performance Benefits

• Token Reduction: 50-80% reduction in token usage with optimized expectations
• Faster Execution: 2-5x speed improvement with batch execution
• Reduced Latency: Fewer round trips between client and server
• Cost Optimization: Lower API costs due to reduced token consumption

Response Diff Detection

The Fast Server includes automatic diff detection to efficiently track changes between consecutive tool executions:

{
  "name": "browser_click",
  "arguments": {
    "element": "Load more button",
    "ref": "#load-more",
    "expectation": {
      "includeSnapshot": true,
      "diffOptions": {
        "enabled": true,
        "threshold": 0.1,
        "format": "unified",
        "maxDiffLines": 50,
        "context": 3
      }
    }
  }
}

Diff Detection Benefits

• Minimal token usage: Only changed content is shown instead of full snapshots
• Change tracking: Automatically detects what changed after actions
• Flexible formats: Choose between unified, split, or minimal diff formats
• Smart caching: Compares against previous response from the same tool

When to Use Diff Detection

1. UI interactions without navigation: Clicks, typing, hover effects
2. Dynamic content updates: Loading more items, real-time updates
3. Form interactions: Track changes as users fill forms
4. Selective monitoring: Use with CSS selectors to track specific areas

{
  "name": "browser_type",
  "arguments": {
    "element": "Search input",
    "ref": "#search",
    "text": "playwright",
    "expectation": {
      "includeSnapshot": true,
      "snapshotOptions": {
        "selector": "#search-results"
      },
      "diffOptions": {
        "enabled": true,
        "format": "minimal"
      }
    }
  }
}

Best Practices

1. Use batch execution for multi-step workflows
2. Enable diff detection for actions without page navigation
3. Disable snapshots for intermediate steps that don’t need verification
4. Use selective snapshots with CSS selectors for large pages
5. Filter console messages to relevant levels only
6. Combine global and step-specific expectations for fine-grained control
7. Use minimal diff format for maximum token savings

Diagnostic System Examples

Find alternative elements when selectors fail:

{
  "name": "browser_find_elements",
  "arguments": {
    "searchCriteria": {
      "text": "Submit",
      "role": "button"
    },
    "maxResults": 5
  }
}

Generate comprehensive page diagnostics:

{
  "name": "browser_diagnose",
  "arguments": {
    "includePerformanceMetrics": true,
    "includeAccessibilityInfo": true,
    "includeTroubleshootingSuggestions": true
  }
}

Debug automation failures with enhanced errors: All tools automatically provide enhanced error messages with:

• Alternative element suggestions
• Page structure analysis
• Context-aware troubleshooting tips
• Performance insights

Network Request Filtering

The browser_network_requests tool provides advanced filtering capabilities to reduce token usage by up to 80-95% when working with network logs.

Basic Usage Examples

// Filter API requests only
{
  "name": "browser_network_requests",
  "arguments": {
    "urlPatterns": ["api/", "/graphql"]
  }
}

// Exclude analytics and tracking
{
  "name": "browser_network_requests", 
  "arguments": {
    "excludeUrlPatterns": ["analytics", "tracking", "ads"]
  }
}

// Success responses only
{
  "name": "browser_network_requests",
  "arguments": {
    "statusRanges": [{ "min": 200, "max": 299 }]
  }
}

// Recent errors only
{
  "name": "browser_network_requests",
  "arguments": {
    "statusRanges": [{ "min": 400, "max": 599 }],
    "maxRequests": 5,
    "newestFirst": true
  }
}

Advanced Filtering

// Complex filtering for API debugging
{
  "name": "browser_network_requests",
  "arguments": {
    "urlPatterns": ["/api/users", "/api/posts"],
    "excludeUrlPatterns": ["/api/health"],
    "methods": ["GET", "POST"],
    "statusRanges": [
      { "min": 200, "max": 299 },
      { "min": 400, "max": 499 }
    ],
    "maxRequests": 10,
    "newestFirst": true
  }
}

// Monitor only failed requests
{
  "name": "browser_network_requests", 
  "arguments": {
    "statusRanges": [
      { "min": 400, "max": 499 },
      { "min": 500, "max": 599 }
    ],
    "maxRequests": 3
  }
}

Regex Pattern Support

{
  "name": "browser_network_requests",
  "arguments": {
    "urlPatterns": ["^/api/v[0-9]+/users$"],
    "excludeUrlPatterns": ["\\.(css|js|png)$"]
  }
}

Token Optimization Benefits

• Massive reduction: 80-95% fewer tokens for large applications
• Focused debugging: See only relevant network activity
• Performance monitoring: Track specific endpoints or error patterns
• Cost savings: Lower API costs due to reduced token usage

When to Use Network Filtering

1. API debugging: Focus on specific endpoints and methods
2. Error monitoring: Track only failed requests
3. Performance analysis: Monitor slow or problematic endpoints
4. Large applications: Reduce overwhelming network logs
5. Token management: Stay within LLM context limits

Migration Guide

Existing code continues to work without changes. To optimize:

1. Start by adding expectation: { includeSnapshot: false } to intermediate steps
2. Use batch execution for sequences of 3+ operations
3. Gradually fine-tune expectations based on your specific needs
4. Use diagnostic tools when automation fails or needs debugging
5. Set --tool-profile=full before upgrading when a client depends on the complete static tools/list response.