Playwright

Playwright MCP is a server that lets you automate and interact with web pages using Playwright through structured accessibility data. It enables large language models to drive browser actions purely from data snapshots, avoiding image-based inputs and vision models while remaining fast and deterministic.

How to use

You connect an MCP client to the Playwright MCP server to perform browser automation through structured data. Start a session, then request actions like navigating to a URL, clicking elements, filling forms, or extracting accessibility snapshots. Use the accessibility snapshot of the page to identify targets and verify results, instead of relying on screenshots.

How to install

Prerequisites you need before installation: Node.js 18 or newer. You also need an MCP client such as VS Code, Cursor, Windsurf, Claude Desktop, Goose, or any other MCP client.

1. Install the Playwright MCP server using the standard config. Run this configuration in your MCP manager or editor to load the server:

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

Additional installation options

The Playwright MCP server can also be installed via alternative methods shown here. You can run a standalone server with an explicit port, or run via Docker for headless deployments.

Standalone server example with a port:

npx @playwright/mcp@latest --port 8931

Docker deployment

Docker lets you run the Playwright MCP server as a container. Use one of the following configurations.

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

Docker long-running container start

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

Programmatic usage

You can integrate Playwright MCP programmatically by creating a connection and attaching a transport. This is useful for custom servers or IDE integrations.

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.connect(transport);

  // ...
});

Configuration file

You can configure the Playwright MCP server with a JSON file and point the server to use it with the --config option.

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

Configuration options (summary)

The server accepts a broad set of options to control browser behavior, network access, and output. Key categories include browser settings, server bind options, capabilities, and output directories. The following is a concise overview of the available flags.

--host <host> --port <port> --headless --config <path> --output-dir <path> --shared-browser-context --isolated --storage-state <path> --viewport-size <widthxheight> --device <device> --user-data-dir <path>

Standalone and Docker notes

If you run headed browsers in environments without a display, start the standalone server and connect to it via the client using the provided URL.

Security and usage tips

Use isolated contexts for test sessions to avoid cross-session data leakage. Persist or share browser state only when you need to retain login sessions across runs, and manage storage state via configuration.

Available tools

browser_click

Perform click on a web page with a target element described by the user and the exact reference from the page snapshot.

browser_close

Close the page or browser context.

browser_console_messages

Return all console messages from the page; can filter to errors only.

browser_drag

Drag from a source element to a target element using the given references.

browser_evaluate

Evaluate a JavaScript expression on the page or a specific element.

browser_file_upload

Upload one or multiple files to an input element.

browser_fill_form

Fill multiple fields on a form with provided data.

browser_handle_dialog

Handle an open dialog by accepting or providing prompt text.

browser_hover

Hover the mouse over a specified element.

browser_navigate

Navigate the browser to a given URL.

browser_navigate_back

Navigate back to the previous page.

browser_network_requests

List all network requests captured since page load.

browser_press_key

Press a key on the keyboard or input a character.

browser_resize

Resize the browser window to specified dimensions.

browser_select_option

Select a value from a dropdown or select element.

browser_snapshot

Capture an accessibility snapshot of the current page.

browser_take_screenshot

Take a screenshot of the current page or a subset of the page.

browser_type

Type text into an editable element and optionally submit.

browser_wait_for

Wait for specific text to appear or disappear, or for a timeout.

browser_tabs

Manage tabs: list, create, close, or switch between tabs.

browser_install

Install the browser specified in the server configuration.

browser_mouse_click_xy

Click at a given screen coordinate.

browser_mouse_drag_xy

Drag the mouse between two coordinates.

browser_mouse_move_xy

Move the mouse to a specific coordinate.

browser_pdf_save

Save the current page as a PDF.

browser_start_tracing

Start tracing to capture performance data.

browser_stop_tracing

Stop tracing and save the trace data.

browser_verify_element_visible

Check that a specific element is visible on the page.

browser_verify_list_visible

Verify that the list of items is visible and matches expected values.

browser_verify_text_visible

Verify that the given text is visible on the page.

browser_verify_value

Verify the value of a form control or element.