Playwright MCP Server

How to use

You use an MCP client to connect to the Playwright MCP server. Start the server on a port or run it as a remote HTTP service, then point your client’s mcpServers configuration to the server. The server exposes a rich set of automation tools that let you click, type, navigate, capture snapshots, inspect network activity, and perform scripted actions on web pages. Use the HTTP URL when running the server as a remote service, or use a local stdio setup to spawn the MCP process directly from your tooling.

Two common ways to connect are: either run the server as an HTTP endpoint and supply the URL to your client, or run a local process (stdio) that the client spawns and communicates with via standard input/output.

How to install

Prerequisites: you need Node.js 18 or newer installed on your machine.

Install and run the Playwright MCP server in stdio mode from a shell, then connect a client to it. The standard approach is to use the executable via a package manager to start the MCP server with the desired port.

Additional configuration and usage notes

Standalone server with HTTP transport is started by running the MCP server on a port, for example: npx @playwright/mcp@latest --port 8931. In this mode, clients connect via an HTTP URL such as http://localhost:8931/mcp.

You can also run the server in a Docker container. The minimal container-based configuration uses a stdio entry with Docker, for example: the server can be launched with a Docker run command and reached at port 8931.

Configuration for clients is typically provided as an mcpServers object, including either an http URL or a stdio command with arguments. Ensure each entry includes the required fields (url for http, command and args for stdio).

Configuration

The server supports a wide range of options to customize behavior, timeouts, security, and profiling. You can specify browser type and launch options, context settings, storage state, initialization scripts, and various timeouts. The options are expressed in a JSON schema that aligns with the configuration object used to start the server. You can also enable optional features such as saving session data, traces, and videos, and you can control which origins and hosts the server can access.

Typical configuration sections include: browser settings (type, isolated mode, user data dir, launch options, context options), server transport (port, host, allowed hosts), capabilities (core features, pdf, vision, devtools), output and logging options, console level, network origins, test id attribute, timeouts, image handling, and tracing controls. You may also provide initial state via storage files or a preloaded storage state.

Standalone MCP server

Run the MCP server in an environment with a display by starting it on a port to enable HTTP transport.

Example start command and client configuration:

npx @playwright/mcp@latest --port 8931
```

```js
{
  "mcpServers": {
    "playwright": {
      "url": "http://localhost:8931/mcp"
    }
  }
}

Docker

The Docker-based setup supports headless Chromium and exposes port 8931 for MCP clients.

Option 1: run the official image as a one-off container using the standard MCP entry points.

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

Option 2: run the container as a long-lived service and expose the port for external clients.

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 --host 0.0.0.0

Programmatic usage

You can create a headless Playwright MCP server instance programmatically and connect a transport for communication.

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);
});

browser_click

Perform click on a web page

browser_close

Close the page

browser_console_messages

Returns all console messages

browser_drag

Perform drag and drop between two elements

browser_evaluate

Evaluate JavaScript expression on page or element

browser_file_upload

Upload one or multiple files

browser_fill_form

Fill multiple form fields

browser_handle_dialog

Handle a dialog

browser_hover

Hover over element on page

browser_navigate

Navigate to a URL

browser_navigate_back

Go back to the previous page in the history

browser_network_requests

List network requests

browser_press_key

Press a key on the keyboard

browser_resize

Resize the browser window

browser_run_code

Run Playwright code snippet

browser_select_option

Select option in a dropdown

browser_snapshot

Page snapshot for accessibility auditing

browser_take_screenshot

Take a screenshot of the current page

browser_type

Type text into an editable element

browser_wait_for

Wait for text to appear or disappear or a time to pass

browser_tabs

Manage tabs: list, create, close, or select

browser_install

Install the browser specified in the config

browser_mouse_click_xy

Click at a given position with the left mouse button

browser_mouse_down

Press mouse button down

browser_mouse_drag_xy

Drag mouse to a position

browser_mouse_move_xy

Move mouse to a position

browser_mouse_up

Press mouse up

browser_mouse_wheel

Scroll mouse wheel

browser_pdf_save

Save page as PDF

browser_generate_locator

Create locator for element in tests

browser_verify_element_visible

Verify element is visible on the page

browser_verify_list_visible

Verify list is visible on the page

browser_verify_text_visible

Verify text is visible on the page

browser_verify_value

Verify element value