@tontoko/fast-playwright-mcp

v0.2.0

Published

a month ago

Context-efficient Playwright tools for MCP

0High
0Medium
0Low

tontoko

Fast Playwright MCP

This MCP server is a fork of the Microsoft one. https://github.com/microsoft/playwright-mcp

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:

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

Use the Claude Code CLI to add the Playwright MCP server:

claude mcp add fast-playwright npx @tontoko/fast-playwright-mcp@latest

Follow the MCP install guide, use the standard config above.

Click the button to install:

Or install manually:

Go to Cursor Settings -> MCP -> Add new MCP Server. Name to your liking, use command type with the command npx @tontoko/fast-playwright-mcp@latest. You can also verify config or add command like arguments via clicking Edit.

Follow the MCP install guide, use the standard config above.

Click the button to install:

Or install manually:

Go to Advanced settings -> Extensions -> Add custom extension. Name to your liking, use type STDIO, and set the command to npx @tontoko/fast-playwright-mcp. Click "Add Extension".

Click the button to install:

Or install manually:

Go to Program in the right sidebar -> Install -> Edit mcp.json. Use the standard config above.

Follow the MCP Servers documentation. For example in ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "playwright": {
      "type": "local",
      "command": [
        "npx",
        "@tontoko/fast-playwright-mcp"
      ],
      "enabled": true
    }
  }
}

Open Qodo Gen chat panel in VSCode or IntelliJ → Connect more tools → + Add new MCP → Paste the standard config above.

Click Save.

Click the button to install:

Or install manually:

Follow the MCP install guide, use the standard config above. You can also install the Playwright MCP server using the VS Code CLI:

# For VS Code
code --add-mcp '{"name":"fast-playwright","command":"npx","args":["@tontoko/fast-playwright-mcp@latest"]}'

After installation, the Playwright MCP server will be available for use with your GitHub Copilot agent in VS Code.

Follow Windsurf MCP documentation. Use the standard config above.

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

{
  /**
   * Tool catalog profile. Adaptive is the 0.2 default; full restores the
   * pre-0.2 static catalog and minimal exposes only the discovery gateways.
   */
  toolProfile?: 'adaptive' | 'full' | 'minimal';

  browser?: {
    /**
     * The browser to use.
     */
    browserName?: 'chromium' | 'firefox' | 'webkit';

    /**
     * Keep the browser profile in memory. By default the profile is written
     * under the operating system's temporary Playwright registry directory.
     */
    isolated?: boolean;

    /**
     * Path to the user data directory. Supplying this overrides the generated
     * persistent profile location.
     */
    userDataDir?: string;

    /**
     * Launch options passed to Playwright.
     */
    launchOptions?: {
      channel?: string;
      executablePath?: string;
      headless?: boolean;
      args?: string[];
    };

    /**
     * Browser context options passed to Playwright.
     */
    contextOptions?: Record<string, unknown>;

    /**
     * Existing Chrome DevTools Protocol endpoint.
     */
    cdpEndpoint?: string;

    /**
     * HTTP headers sent when connecting to the CDP endpoint.
     */
    cdpHeaders?: Record<string, string>;

    /**
     * CDP connection timeout in milliseconds.
     */
    cdpTimeout?: number;

    /**
     * Playwright remote browser endpoint.
     */
    remoteEndpoint?: string;
  };

  server?: {
    host?: string;
    port?: number;
    allowedHosts?: string[];
  };

  capabilities?: Array<'vision' | 'pdf' | 'apps'>;
  outputDir?: string;
  outputMode?: 'file' | 'stdio';
  outputMaxSize?: number;
  secrets?: Record<string, string>;
  testIdAttribute?: string;
  timeouts?: {
    action?: number;
    navigation?: number;
    expect?: number;
  };
  codegen?: 'typescript' | 'none';
}

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 <hosts>          comma-separated list of allowed HTTP Host
                                   header values
  --allowed-origins <origins>      semicolon-separated list of origins to allow
                                   the browser to request. Default is to allow
                                   all.
  --blocked-origins <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>              browser or chrome channel to use: chrome,
                                   firefox, webkit, or msedge
  --caps <caps>                    comma-separated optional capabilities:
                                   vision, pdf, apps
  --cdp-endpoint <endpoint>        CDP endpoint to connect to
  --cdp-header <header...>         CDP request header in Name: Value form; may
                                   be repeated
  --cdp-timeout <timeout>          CDP connection timeout in milliseconds
  --codegen <mode>                 generated code mode: typescript or none
  --config <path>                  path to the configuration file
  --device <device>                device to emulate, for example: "iPhone 15"
  --executable-path <path>         path to the browser executable
  --headless                       run browser in headless mode, headed by
                                   default
  --host <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 <mode>         whether image responses are allow or omit
  --no-sandbox                     disable the Chromium sandbox for process
                                   types that normally use it
  --output-dir <path>              directory for output files
  --output-max-size <bytes>        maximum output directory size in bytes; zero
                                   disables eviction
  --port <port>                    port to listen on for HTTP transport
  --proxy-bypass <bypass>          comma-separated domains to bypass the proxy
  --proxy-server <proxy>           proxy server URL
  --save-session                   save the Playwright MCP session
  --save-trace                     save the Playwright trace
  --secrets <path>                 dotenv file containing values to redact
  --storage-state <path>           path to storage state for isolated sessions
  --test-id-attribute <attribute>  attribute used by test-id selectors
  --timeout-action <timeout>       default action timeout in milliseconds
  --timeout-expect <timeout>       default expectation timeout in milliseconds
  --timeout-navigation <timeout>   default navigation timeout in milliseconds
  --timeout-settle <timeout>       delay after browser actions before capturing
                                   the response, in milliseconds
  --tool-profile <profile>         tool catalog profile: adaptive, full, or
                                   minimal
  --user-agent <ua string>         browser user-agent string
  --user-data-dir <path>           browser user data directory
  --viewport-size <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 <chromium|firefox|webkit> with --executable-path <full 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

browser_batch_execute
- Title: Batch Execute Browser Actions
- Description: Execute multiple registered browser actions in sequence with one response.
- Parameters:
  - steps (array): Array of steps to execute in sequence. Recommended for form filling (multiple type→click), multi-step navigation, any workflow with 2+ known steps. Saves 90% tokens vs individual calls. Example: [{tool:"browser_navigate",arguments:{url:"https://example.com"}},{tool:"browser_type",arguments:{selectors:[{css:"#user"}],text:"john"}},{tool:"browser_click",arguments:{selectors:[{css:"#btn"}]}}]
  - stopOnFirstError (boolean, optional): Stop entire batch on first error
  - globalExpectation (optional): Default expectation for all steps. Recommended: {includeSnapshot:false,snapshotOptions:{selector:"#app"},diffOptions:{enabled:true}}. Per-step override with steps[].expectation
- Read-only: false

browser_click
- Title: Perform click on web page
- Description: Perform click on web page
- Parameters:
  - selectors (array): Array of element selectors (max 5). Selectors are tried in order until one succeeds (fallback mechanism). Multiple matches trigger an error with candidate list. Supports: ref (highest priority), CSS (#id, .class, tag), role (button, textbox, etc.), text content. Example: [{css: "#submit"}, {role: "button", text: "Submit"}] - tries ID first, falls back to role+text
  - doubleClick (boolean, optional): Double-click if true
  - button (string, optional): Mouse button (default: left)
  - expectation (object, optional): Page state capture config. Use batch_execute for multi-clicks
- Read-only: false

browser_close
- Title: Close browser
- Description: Close the page
- Parameters: None
- Read-only: false

browser_console_messages
- Title: Get console messages
- Description: Returns all console messages
- Parameters:
  - consoleOptions (object, optional): undefined
- Read-only: true

browser_diagnose
- Title: Diagnose page
- Description: Analyze page complexity, iframe count, DOM size, modal state, element statistics, and performance characteristics.
- Parameters:
  - searchForElements (object, optional): Search for specific elements and include them in the report
  - includePerformanceMetrics (boolean, optional): Include performance metrics in the report
  - includeAccessibilityInfo (boolean, optional): Include accessibility information
  - includeTroubleshootingSuggestions (boolean, optional): Include troubleshooting suggestions
  - diagnosticLevel (string, optional): Level of diagnostic detail: none (no diagnostics), basic (critical only), standard (default), detailed (with metrics), full (all info)
  - useParallelAnalysis (boolean, optional): Use Phase 2 parallel analysis for improved performance and resource monitoring
  - useUnifiedSystem (boolean, optional): Use Phase 3 unified diagnostic system with enhanced error handling and monitoring
  - configOverrides (object, optional): Runtime configuration overrides for diagnostic system
  - includeSystemStats (boolean, optional): Include unified system statistics and health information
  - expectation (object, optional): undefined
- Read-only: true

browser_drag
- Title: Drag mouse
- Description: Perform drag and drop between two elements
- Parameters:
  - startSelectors (array): Source element selectors for drag start
  - endSelectors (array): Target element selectors for drag end
  - expectation (object, optional): Page state after drag. Use batch_execute for workflows
- Read-only: false

browser_evaluate
- Title: Evaluate JavaScript
- Description: Evaluate JavaScript expression on page or element and return result
- Parameters:
  - function (string): JS function: () => {...} or (element) => {...}
  - selectors (array, optional): Optional element selectors. If provided, function receives element as parameter
  - expectation (object, optional): Page state config. false for data extraction, true for DOM changes
- Read-only: false

browser_file_upload
- Title: Upload files
- Description: Upload one or multiple files to file input
- Parameters:
  - paths (array): Absolute paths to upload (array)
  - expectation (object, optional): Page state config. Use batch_execute for click→upload
- Read-only: false

browser_find
- Title: Find in page snapshot
- Description: Search the current accessibility snapshot and return compact matching context.
- Parameters:
  - query (string): undefined
  - regex (boolean, optional): undefined
  - caseSensitive (boolean, optional): undefined
  - maxResults (integer, optional): undefined
  - contextLines (integer, optional): undefined
  - expectation (object, optional): undefined
- Read-only: true

browser_find_elements
- Title: Find elements
- Description: Find elements on the page using multiple search criteria such as text, role, tag name, or attributes. Returns matching elements sorted by confidence.
- Parameters:
  - searchCriteria (object): Search criteria for finding elements
  - maxResults (number, optional): Maximum number of results to return
  - includeDiagnosticInfo (boolean, optional): Include diagnostic information about the page
  - useUnifiedSystem (boolean, optional): Use unified diagnostic system for enhanced error handling
  - enableEnhancedDiscovery (boolean, optional): Enable enhanced element discovery with contextual suggestions
  - performanceThreshold (number, optional): Performance threshold in milliseconds for element discovery
  - expectation (object, optional): undefined
- Read-only: true

browser_handle_dialog
- Title: Handle a dialog
- Description: Handle a dialog (alert, confirm, prompt)
- Parameters:
  - accept (boolean): Accept (true) or dismiss (false)
  - promptText (string, optional): Text for prompt dialogs
  - expectation (object, optional): Page state after dialog. Use batch_execute for workflows
- Read-only: false

browser_hover
- Title: Hover mouse
- Description: Hover over element on page
- Parameters:
  - selectors (array): Array of element selectors (max 5). Selectors are tried in order until one succeeds (fallback mechanism). Multiple matches trigger an error with candidate list. Supports: ref (highest priority), CSS (#id, .class, tag), role (button, textbox, etc.), text content. Example: [{css: "#submit"}, {role: "button", text: "Submit"}] - tries ID first, falls back to role+text
  - expectation (object, optional): Page state after hover. Use batch_execute for hover→click
- Read-only: false

browser_inspect_html
- Title: HTML inspection
- Description: Extract filtered HTML with configurable depth, output format, size limits, and automatic truncation.
- Parameters:
  - selectors (array): Array of element selectors to inspect
  - depth (number, optional): Maximum hierarchy depth to extract
  - includeStyles (boolean, optional): Include computed CSS styles
  - maxSize (number, optional): Maximum size in bytes (1KB-500KB)
  - format (string, optional): Output format
  - includeAttributes (boolean, optional): Include element attributes
  - preserveWhitespace (boolean, optional): Preserve whitespace in content
  - excludeSelector (string, optional): CSS selector to exclude elements
  - includeSuggestions (boolean, optional): Include CSS selector suggestions in output
  - includeChildren (boolean, optional): Include child elements in extraction
  - optimizeForLLM (boolean, optional): Optimize extracted HTML for LLM consumption
  - expectation (object, optional): Page state config (minimal for HTML inspection)
- Read-only: true

browser_navigate
- Title: Navigate to a URL
- Description: Navigate to a URL
- Parameters:
  - url (string): The URL to navigate to
  - expectation (object, optional): Page state after navigation
- Read-only: false

browser_navigate_back
- Title: Go back to previous page
- Description: Go back to previous page
- Parameters:
  - expectation (object, optional): Page state after going back
- Read-only: false

browser_navigate_forward
- Title: Go forward to next page
- Description: Go forward to next page
- Parameters:
  - expectation (object, optional): Page state after going forward
- Read-only: false

browser_network_requests
- Title: List network requests
- Description: Returns network requests since loading the page with optional filtering
- Parameters:
  - urlPatterns (array, optional): URL patterns to filter (supports regex)
  - excludeUrlPatterns (array, optional): URL patterns to exclude (takes precedence)
  - statusRanges (array, optional): Status code ranges (e.g., [{min:200,max:299}])
  - methods (array, optional): HTTP methods to filter
  - maxRequests (number, optional): Max requests to return (default: 20)
  - newestFirst (boolean, optional): Order by timestamp (default: newest first)
- Read-only: true

browser_press_key
- Title: Press a key
- Description: Press a key on the keyboard
- Parameters:
  - key (string): Key to press
  - expectation (object, optional): Page state config. Use batch_execute for multiple keys
- Read-only: false

browser_resize
- Title: Resize browser window
- Description: Resize the browser window
- Parameters:
  - width (number): Width of the browser window
  - height (number): Height of the browser window
  - expectation (object, optional): undefined
- Read-only: false

browser_select_option
- Title: Select option
- Description: Select option in dropdown
- Parameters:
  - selectors (array): Array of element selectors (max 5). Selectors are tried in order until one succeeds (fallback mechanism). Multiple matches trigger an error with candidate list. Supports: ref (highest priority), CSS (#id, .class, tag), role (button, textbox, etc.), text content. Example: [{css: "#submit"}, {role: "button", text: "Submit"}] - tries ID first, falls back to role+text
  - values (array): Values to select (array)
  - expectation (object, optional): Page state after selection. Use batch_execute for forms
- Read-only: false

browser_snapshot
- Title: Page snapshot
- Description: Capture accessibility snapshot of current page
- Parameters:
  - expectation (object, optional): Page state config
- Read-only: true

browser_take_screenshot
- Title: Take a screenshot
- Description: Take a screenshot of current page and return image data
- Parameters:
  - type (string, optional): Image format. When omitted, inferred from filename or defaults to png.
  - filename (string, optional): File name to save the screenshot to. Defaults to page-{timestamp}.{png|jpeg|webp} if not specified.
  - selectors (array, optional): Optional element selectors for element screenshots. If not provided, viewport screenshot will be taken.
  - scale (string, optional): Use CSS pixels or device pixels for the screenshot.
  - fullPage (boolean, optional): When true, takes a screenshot of the full scrollable page, instead of the currently visible viewport. Cannot be used with element screenshots.
  - expectation (object, optional): Additional page state config
- Read-only: false

browser_type
- Title: Type text
- Description: Type text into editable element
- Parameters:
  - selectors (array): Array of element selectors (max 5) supporting ref, role, CSS, or text-based selection
  - text (string): Text to type into the element
  - submit (boolean, optional): Press Enter after typing if true
  - slowly (boolean, optional): Type slowly for auto-complete if true
  - expectation (object, optional): Page state config. Use batch_execute for forms
- Read-only: false

browser_wait_for
- Title: Wait for
- Description: Wait for text to appear or disappear or a specified time to pass
- Parameters:
  - time (number, optional): Wait time in seconds
  - text (string, optional): undefined
  - textGone (string, optional): undefined
  - expectation (object, optional): Page state after wait
- Read-only: true

browser_tab_close
- Title: Close a tab
- Description: Close a tab by index or close current tab
- Parameters:
  - index (number, optional): Tab index to close (omit for current)
  - expectation (object, optional): Page state after close
- Read-only: false

browser_tab_list
- Title: List tabs
- Description: List browser tabs with titles and URLs
- Parameters:
  - expectation (object, optional): Page state config
- Read-only: true

browser_tab_new
- Title: Open a new tab
- Description: Open a new tab
- Parameters:
  - url (string, optional): URL for new tab (optional)
  - expectation (object, optional): Page state of new tab
- Read-only: false

browser_tab_select
- Title: Select a tab
- Description: Select a tab by index
- Parameters:
  - index (number): The index of the tab to select
  - expectation (object, optional): Page state after tab switch
- Read-only: false

browser_install
- Title: Install the browser specified in the config
- Description: Install the browser specified in the config. Call this if you get an error about the browser not being installed.
- Parameters: None
- Read-only: false

browser_mouse_click_xy
- Title: Click
- Description: Click at specific coordinates
- Parameters:
  - element (string): undefined
  - x (number): X coordinate (requires --caps=vision)
  - y (number): Y coordinate (requires --caps=vision)
  - expectation (object, optional): Page state after click. Prefer element ref over coords
- Read-only: false

browser_mouse_drag_xy
- Title: Drag mouse
- Description: Drag from one coordinate to another
- Parameters:
  - element (string): undefined
  - startX (number): Start X (requires --caps=vision)
  - startY (number): Start Y (requires --caps=vision)
  - endX (number): End X
  - endY (number): End Y
  - expectation (object, optional): Page state after drag. Prefer element refs over coords
- Read-only: false

browser_mouse_move_xy
- Title: Move mouse
- Description: Move the mouse to coordinates. Requires the vision capability; prefer element-based interactions when possible.
- Parameters:
  - element (string): undefined
  - x (number): X coordinate
  - y (number): Y coordinate
  - expectation (object, optional): undefined
- Read-only: false

browser_pdf_save
- Title: Save as PDF
- Description: Save page as PDF
- Parameters:
  - filename (string, optional): File name to save the pdf to. Defaults to page-{timestamp}.pdf if not specified.
- Read-only: false

browser_dashboard
- Title: Open browser dashboard
- Description: Open the bundled browser preview and tab-selection dashboard.
- Parameters: None
- Read-only: true

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

UI interactions without navigation: Clicks, typing, hover effects
Dynamic content updates: Loading more items, real-time updates
Form interactions: Track changes as users fill forms
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

Use batch execution for multi-step workflows
Enable diff detection for actions without page navigation
Disable snapshots for intermediate steps that don't need verification
Use selective snapshots with CSS selectors for large pages
Filter console messages to relevant levels only
Combine global and step-specific expectations for fine-grained control
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

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

Migration Guide

Existing code continues to work without changes. To optimize:

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

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Fast Playwright MCP

Key Features

Fast Server Features (This Fork)

Adaptive tool catalog

Security and interoperability controls

Requirements

Getting started

Click the button to install:

Or install manually:

Click the button to install:

Or install manually:

Click the button to install:

Or install manually:

Click the button to install:

Or install manually:

Configuration file

User profile

Configuration

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

Standalone MCP server

Docker

Programmatic usage

Tools

Token Optimization Examples

Basic Expectation Control

Expectation Options

Advanced Snapshot Options

Console Filtering Options

Batch Execution

Basic Batch Execution

Advanced Batch Configuration

Error Handling Options

Tool-Specific Defaults

Performance Benefits

Response Diff Detection

Diff Detection Benefits

When to Use Diff Detection

Best Practices

Diagnostic System Examples

Network Request Filtering

Basic Usage Examples

Advanced Filtering

Regex Pattern Support

Token Optimization Benefits

When to Use Network Filtering

Migration Guide