Playwright

Playwright MCP is a Model Context Protocol server that enables browser automation through Playwright. It provides structured accessibility snapshots so your language models can interact with web pages without relying on screenshots or vision models, delivering fast, deterministic browser actions.

How to use

You connect an MCP client to the Playwright MCP server to perform browser actions via a clean, structured API. Use this server when you want to automate web pages with predictable interactions and accessibility snapshots rather than pixel-based inputs. Start a local server or connect to a remote endpoint, then issue actions like navigate, click, type, or take a page snapshot to drive a browser session.

How to install

Prerequisites you need before running the Playwright MCP server: Node.js 18 or newer. An MCP client such as VS Code with an MCP extension, Windsurf, Claude Desktop, Goose, Cursor, or similar.

// STDIO (local) example start command
npx @playwright/mcp@latest --help

Install and run the server locally using the standard config. This starts the MCP server as a local process that you can connect to via the HTTP transport or via the MCP client directly.

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

Standalone and HTTP transport

You can run the Playwright MCP server as a standalone HTTP service or connect an MCP client to a running server.

To run as a standalone HTTP server on a specific port, start the server with a port option and then point your MCP client to the HTTP URL.

Example start command for HTTP transport on port 8931

npx @playwright/mcp@latest --port 8931

Then configure the client to connect to the HTTP endpoint at http://localhost:8931/mcp.

Docker and programmatic usage

You can run the server inside Docker or use programmatic access to create a connection and transport messages.

Docker example shows a ready-to-run container for MCP interactions (note that this Docker image supports headless Chromium) :

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

Programmatic usage lets you create a Playwright MCP server connection and attach an SSE transport for message exchange in your own application.

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

http.createServer(async (req, res) => {
  // Create a headless Playwright MCP server with SSE transport
  const connection = await createConnection({ browser: { launchOptions: { headless: true } } });
  const transport = new SSEServerTransport('/messages', res);
  await connection.sever.connect(transport);
  // ... your logic
});

Configuration and capabilities

Playwright MCP accepts a comprehensive JSON configuration to tailor browser behavior, network rules, and output. You can specify the browser type, isolation mode, storage state, and server listening options.

> npx @playwright/mcp@latest --help
  --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. If used without the allowlist,
                               requests not matching the blocklist are still
                               allowed.
  --port <port>                port to listen on for SSE transport.
  --config <path>              path to the configuration file.
  --isolated                   keep the browser profile in memory, do not save
                               it to disk.
  --storage-state <path>       path to the storage state file for isolated
                               sessions.
  --viewport-size <size>       specify browser viewport size in pixels, for
                               example "1280, 720"

Security and reliability notes

Use persistent profiles when you want to maintain login state across sessions, or opt for isolated contexts to keep each session separate. If you enable storage state or isolated mode, you control how the browser stores data between runs.

Tools and capabilities

The server exposes a set of programmatic tools to control the browser. These include actions such as clicking elements, navigating pages, taking snapshots, typing text, and more. The full set of capabilities is available to your MCP client for automation tasks.

Troubleshooting and tips

If you encounter issues installing or starting the server, verify you have Node.js 18+ installed, and ensure there are no port conflicts when starting an HTTP server. For isolated mode, provide storage state if you want to reuse preloaded data between sessions.

Notes

This server is designed to let large language models interact with web pages through an accessibility snapshot, avoiding reliance on pixel-based interpretation. It is fast, deterministic, and easy to integrate with MCP clients.

Available tools

browser_click

Perform click on a web page. Includes element description, exact target reference, and optional parameters for doubleClick and which button to use.

browser_close

Close the browser or the current page.

browser_console_messages

Retrieve all console messages from the page.

browser_drag

Drag and drop between two elements using their references.

browser_evaluate

Evaluate JavaScript on the page or a specific element.

browser_file_upload

Upload one or multiple files by providing absolute paths.

browser_handle_dialog

Handle a dialog with options to accept and optional prompt text.

browser_hover

Hover the mouse over a target element.

browser_navigate

Navigate the browser to a specified URL.

browser_navigate_back

Go back to the previous page.

browser_navigate_forward

Go forward to the next page.

browser_network_requests

List all network requests since page load.

browser_press_key

Press a key or a key sequence on the keyboard.

browser_resize

Resize the browser window to specified dimensions.

browser_select_option

Select one or more options in a dropdown.

browser_snapshot

Capture an accessibility snapshot of the current page.

browser_take_screenshot

Take a screenshot of the current page; use snapshot for actions.

browser_type

Type text into an editable element with control over submission and typing speed.

browser_wait_for

Wait for text to appear or disappear or a timeout.

browser_tab_close

Close a browser tab by index or the current tab.

browser_tab_list

List all open browser tabs.

browser_tab_new

Open a new tab and optionally navigate to a URL.

browser_tab_select

Select a tab by index.

browser_install

Install the required browser specified in the configuration.

browser_mouse_click_xy

Click at a specified screen coordinate.

browser_mouse_drag_xy

Drag the mouse from a start to an end coordinate.

browser_mouse_move_xy

Move the mouse to a specific coordinate.

browser_pdf_save

Save the current page as a PDF file.

browser_wait_for

Wait for specific page text to appear or disappear or for a delay.