Playwright MCP Server Documentation

This documentation was retrieved from Context7 for the Playwright Model Context Protocol (MCP) server.

Overview

The Playwright MCP server enables browser automation capabilities through structured accessibility snapshots. It can be integrated with various client applications like VS Code, Cursor, Windsurf, Claude Desktop, and Qodo Gen.

Installation

Basic Configuration

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

Using VS Code CLI

code --add-mcp '{"name":"playwright","command":"npx","args":["@playwright/mcp@latest"]}'

Using Claude Code CLI

claude mcp add playwright npx @playwright/mcp@latest

Command-Line Arguments

--allowed-origins <origins>  semicolon-separated list of origins to allow the browser to request
--blocked-origins <origins>  semicolon-separated list of origins to block the browser from requesting
--block-service-workers      block service workers
--browser <browser>          browser or chrome channel to use (chrome, firefox, webkit, msedge)
--browser-agent <endpoint>   Use browser agent (experimental)
--caps <caps>                comma-separated list of capabilities to enable (tabs, pdf, history, wait, files, install)
--cdp-endpoint <endpoint>    CDP endpoint to connect to
--config <path>              path to the configuration file
--device <device>            device to emulate (e.g., "iPhone 15")
--executable-path <path>     path to the browser executable
--headless                   run browser in headless mode
--host <host>                host to bind server to (default: localhost, use 0.0.0.0 for all interfaces)
--ignore-https-errors        ignore https errors
--isolated                   keep the browser profile in memory, do not save it to disk
--image-responses <mode>     whether to send image responses (allow, omit, auto)
--no-sandbox                 disable the sandbox for all process types
--output-dir <path>          path to the directory for output files
--port <port>                port to listen on for SSE transport
--proxy-bypass <bypass>      comma-separated domains to bypass proxy
--proxy-server <proxy>       specify proxy server
--save-trace                 save the Playwright Trace of the session
--storage-state <path>       path to the storage state file for isolated sessions
--user-agent <ua string>     specify user agent string
--user-data-dir <path>       path to the user data directory
--viewport-size <size>       specify browser viewport size (e.g., "1280, 720")
--vision                     run server that uses screenshots (Aria snapshots are used by default)

Configuration File

Use a JSON configuration file with --config:

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

Configuration Schema

{
  // Browser configuration
  browser?: {
    browserName?: 'chromium' | 'firefox' | 'webkit';
    isolated?: boolean;
    userDataDir?: string;
    launchOptions?: {
      channel?: string;
      headless?: boolean;
      executablePath?: string;
      // ... other Playwright launch options
    };
    contextOptions?: {
      viewport?: { width: number, height: number };
      // ... other Playwright context options
    };
    cdpEndpoint?: string;
    remoteEndpoint?: string;
  },

  // Server configuration
  server?: {
    port?: number;
    host?: string;
  },

  // List of enabled capabilities
  capabilities?: Array<
    'core' |    // Core browser automation
    'tabs' |    // Tab management
    'pdf' |     // PDF generation
    'history' | // Browser history
    'wait' |    // Wait utilities
    'files' |   // File handling
    'install' | // Browser installation
    'testing'   // Testing
  >;

  // Enable vision mode (screenshots instead of accessibility snapshots)
  vision?: boolean;

  // Directory for output files
  outputDir?: string;

  // Network configuration
  network?: {
    allowedOrigins?: string[];
    blockedOrigins?: string[];
  };
 
  noImageResponses?: boolean;
}

API Reference

browser_navigate

Navigate to a URL

Parameters:
- url (string): The URL to navigate to

browser_navigate_back

Go back to the previous page

browser_navigate_forward

Go forward to the next page

Page Interaction

browser_snapshot

Capture accessibility snapshot of the current page (better than screenshot)

browser_click

Perform click on a web page

Parameters:
- element (string): Human-readable element description
- ref (string): Exact target element reference from the page snapshot

browser_drag

Perform drag and drop between two elements

Parameters:
- startElement (string): Human-readable source element description
- startRef (string): Exact source element reference
- endElement (string): Human-readable target element description
- endRef (string): Exact target element reference

browser_hover

Hover over element on page

Parameters:
- element (string): Human-readable element description
- ref (string): Exact target element reference

browser_type

Type text into editable element

Parameters:
- element (string): Human-readable element description
- ref (string): Exact target element reference
- text (string): Text to type
- submit (boolean, optional): Whether to submit entered text (press Enter)
- slowly (boolean, optional): Whether to type one character at a time

browser_select_option

Select an option in a dropdown

Parameters:
- element (string): Human-readable element description
- ref (string): Exact target element reference
- values (array): Array of values to select

browser_press_key

Press a key on the keyboard

Parameters:
- key (string): Name of the key to press (e.g., ArrowLeft, a)

Wait and Timing

browser_wait_for

Wait for text to appear/disappear or time to pass

Parameters:
- time (number, optional): Time to wait in seconds
- text (string, optional): Text to wait for
- textGone (string, optional): Text to wait for to disappear

File Handling

browser_file_upload

Upload one or multiple files

Parameters:
- paths (array): Absolute paths to files to upload

Dialogs

browser_handle_dialog

Handle a dialog

Parameters:
- accept (boolean): Whether to accept the dialog
- promptText (string, optional): Text for prompt dialogs

Screenshots and PDF

browser_take_screenshot

Take a screenshot of the current page

Parameters:
- raw (boolean, optional): Return PNG format without compression
- filename (string, optional): File name to save
- element (string, optional): Element description to screenshot
- ref (string, optional): Element reference

browser_pdf_save

Save page as PDF

Parameters:
- filename (string, optional): File name to save

Tab Management

browser_tab_list

List browser tabs

browser_tab_new

Open a new tab

Parameters:
- url (string, optional): URL to navigate to in new tab

browser_tab_select

Select a tab by index

Parameters:
- index (number): Index of the tab to select

browser_tab_close

Close a tab

Parameters:
- index (number, optional): Index of tab to close (current if not provided)

Browser Management

browser_close

Close the page

browser_resize

Resize the browser window

Parameters:
- width (number): Width of the browser window
- height (number): Height of the browser window

browser_install

Install the browser specified in the config

Debugging

browser_console_messages

Returns all console messages

browser_network_requests

Returns all network requests since loading the page

Testing

browser_generate_playwright_test

Generate a Playwright test for given scenario

Parameters:
- name (string): The name of the test
- description (string): The description of the test
- steps (array): The steps of the test

Vision Mode

Vision mode uses screenshots for visual interactions instead of accessibility snapshots:

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

Vision Mode Additional Tools

browser_screen_capture

Capture the current screen content

browser_screen_screenshot

Take a screenshot of the current page

browser_screen_move_mouse

Move mouse to a given position

Parameters:
- element (string): Element description
- x (number): X coordinate
- y (number): Y coordinate

browser_screen_click

Click left mouse button

Parameters:
- element (string): Element description
- x (number): X coordinate
- y (number): Y coordinate

browser_screen_drag

Drag left mouse button

Parameters:
- element (string): Element description
- startX (number): Start X coordinate
- startY (number): Start Y coordinate
- endX (number): End X coordinate
- endY (number): End Y coordinate

browser_screen_type

Type text

Parameters:
- text (string): Text to type
- submit (boolean, optional): Whether to submit entered text

Standalone Server

Run as standalone server with SSE transport:

npx @playwright/mcp@latest --port 8931

Client configuration for standalone server:

{
  "mcpServers": {
    "playwright": {
      "url": "http://localhost:8931/sse"
    }
  }
}

Isolated Sessions

Run with isolated profile (in-memory):

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--isolated",
        "--storage-state={path/to/storage.json}"
      ]
    }
  }
}

Docker Support

Run in Docker container:

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

Build custom Docker image:

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

Default Profile Locations

Windows: %USERPROFILE%\AppData\Local\ms-playwright\mcp-{channel}-profile
macOS: ~/Library/Caches/ms-playwright/mcp-{channel}-profile
Linux: ~/.cache/ms-playwright/mcp-{channel}-profile

Programmatic Usage

import http from 'http';
import { createConnection } from '@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.server.connect(transport);
});

On this page