Home / MCP / Playwright MCP Server

Playwright MCP Server

Provides browser automation via Playwright MCP server using accessibility snapshots for structured interactions.

typescript

Installation

Add the following to your MCP client configuration file.

Configuration

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

The Playwright MCP server lets you automate browser tasks using Playwright and structured accessibility data, so you can drive web pages with language models without relying on screenshots or vision models. It’s fast, lightweight, and guarantees deterministic tool usage by operating on the page’s accessibility tree.

How to use

You interact with a Playwright MCP server through an MCP client. Install the server in your preferred client, then connect to it to automate browser actions such as navigating pages, clicking elements, typing text, and waiting for content. Use the server to perform actions on live pages using structured data rather than pixel-based cues, which helps your model reason about web interactions more reliably.

How to install

Prerequisites: Node.js 18 or newer. Ensure you have a compatible MCP client installed (VS Code, Cursor, Windsurf, Claude Desktop, Claude Code, Qodo Gen, etc.). Then install and configure the Playwright MCP server in your client of choice using the provided commands.

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

Install in VS Code using the CLI. This adds the Playwright MCP server so you can use it with your GitHub Copilot agent in VS Code.

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

Install in Cursor by adding a new MCP server with the following configuration, or verify/edit existing settings to include the Playwright MCP server.

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

Install in Windsurf by using the same configuration pattern as other MCP servers.

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

Install in Claude Desktop by using the same configuration form as other MCP servers.

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

Install in Claude Code using the Claude Code CLI to add the Playwright MCP server.

claude mcp add playwright npx @playwright/mcp@latest

Install in Qodo Gen by adding the Playwright MCP server configuration in the chat panel, then Save.

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

Standalone startup: you can run the server headless or with a display. To run a standalone instance that exposes an SSE endpoint, start with a port and then configure your client to connect to that SSE URL.

npx @playwright/mcp@latest --port 8931

To connect a client to the standalone server, configure the client to use the SSE endpoint at the address you started, for example http://localhost:8931/sse.

Configuration

Playwright MCP server supports a broad set of command-line arguments and a configuration file. The following options are available when starting the server. They control origins, browser choice, device emulation, storage state, and various features.

> 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.
  --block-service-workers      block service workers
  --browser <browser>          browser or chrome channel to use, possible
                               values: chrome, firefox, webkit, msedge.
  --browser-agent <endpoint>   Use browser agent (experimental).
  --caps <caps>                comma-separated list of capabilities to enable,
                               possible values: tabs, pdf, history, wait, files,
                               install. Default is all.
  --cdp-endpoint <endpoint>    CDP endpoint to connect to.
  --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 to 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 to the client.
                               Can be "allow", "omit", or "auto". Defaults to
                               "auto", which sends images if the client can
                               display them.
  --no-sandbox                 disable the sandbox for all process types that
                               are normally sandboxed.
  --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, for
                               example ".com,chromium.org,.domain.com"
  --proxy-server <proxy>       specify proxy server, for example
                               "http://myproxy:3128" or "socks5://myproxy:8080"
  --save-trace                 Whether to save the Playwright Trace of the
                               session into the output directory.
  --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. If not
                               specified, a temporary directory will be created.
  --viewport-size <size>       specify browser viewport size in pixels, for
                               example "1280, 720"
  --vision                     Run server that uses screenshots (Aria snapshots
                               are used by default)

Configuration file

You can configure the Playwright MCP server using a JSON configuration file. Specify the path to this file with the --config option when starting the server.

{
  // Browser configuration
  browser?: {
    // Browser type to use (chromium, firefox, or webkit)
    browserName?: 'chromium' | 'firefox' | 'webkit';

    // Keep the browser profile in memory, do not save it to disk.
    isolated?: boolean;

    // Path to user data directory for browser profile persistence
    userDataDir?: string;

    // Browser launch options (see Playwright docs)
    // @see https://playwright.dev/docs/api/class-browsertype#browser-type-launch
    launchOptions?: {
      channel?: string;        // Browser channel (e.g. 'chrome')
      headless?: boolean;      // Run in headless mode
      executablePath?: string; // Path to browser executable
      // ... other Playwright launch options
    };

    // Browser context options
    // @see https://playwright.dev/docs/api/class-browser#browser-new-context
    contextOptions?: {
      viewport?: { width: number, height: number };
      // ... other Playwright context options
    };

    // CDP endpoint for connecting to existing browser
    cdpEndpoint?: string;

    // Remote Playwright server endpoint
    remoteEndpoint?: string;
  },

  // Server configuration
  server?: {
    port?: number;  // Port to listen on
    host?: string;  // Host to bind to (default: localhost)
  },

  // 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?: {
    // List of origins to allow the browser to request. Default is to allow all. Origins matching both `allowedOrigins` and `blockedOrigins` will be blocked.
    allowedOrigins?: string[];

    // List of origins to block the browser to request. Origins matching both `allowedOrigins` and `blockedOrigins` will be blocked.
    blockedOrigins?: string[];
  };
 
  /**
   * Do not send image responses to the client.
   */
  noImageResponses?: boolean;
}

Stand-alone MCP server

If you run the MCP server in an environment with a display, you can start it as a standalone service that exposes an SSE endpoint. Pass a port, then connect your MCP client to the SSE URL.

npx @playwright/mcp@latest --port 8931

// In the client configuration, point to the SSE endpoint
{
  "mcpServers": {
    "playwright": {
      "url": "http://localhost:8931/sse"
    }
  }
}

Docker

You can run the Playwright MCP server in Docker. The Docker image currently supports headless chromium.

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

If you prefer to build the image yourself, you can run: docker build -t mcr.microsoft.com/playwright/mcp .

Programmatic usage

You can create a server programmatically and expose an SSE transport to integrate with your MCP client. The example below shows creating a headless Playwright MCP server with an SSE transport.

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

  // ...
});

Tools and interactions

The Playwright MCP server offers a collection of actions you can invoke to interact with web pages. These tools run through the MCP client and operate on the page's accessibility snapshots or, optionally, vision-based interactions if you enable vision mode.

Key interactions include browsing, clicking, typing, selecting options, dragging, waiting for text, and handling dialogs. You can also capture page snapshots, take screenshots or PDFs, and manage browser tabs.

Available tools

browser_snapshot

Capture accessibility snapshot of the current page, this is better than screenshot.

browser_click

Perform click on a web page.

browser_drag

Drag and drop between two elements.

browser_hover

Hover over element on page.

browser_type

Type text into an editable element.

browser_select_option

Select an option in a dropdown.

browser_press_key

Press a key on the keyboard.

browser_wait_for

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

browser_file_upload

Upload one or multiple files.

browser_handle_dialog

Handle a dialog by accepting or providing prompt text.

browser_navigate

Navigate to a URL.

browser_navigate_back

Go back to the previous page.

browser_navigate_forward

Go forward to the next page.

browser_take_screenshot

Take a screenshot of the current page.

browser_pdf_save

Save page as PDF.

browser_network_requests

List all network requests since page load.

browser_console_messages

Get console messages.

browser_install

Install the browser specified in the config.

browser_close

Close the browser.

browser_resize

Resize the browser window.

browser_tab_list

List browser tabs.

browser_tab_new

Open a new tab.

browser_tab_select

Select a tab by index.

browser_tab_close

Close a tab by index.

browser_generate_playwright_test

Generate a Playwright test for a given scenario.

browser_screen_capture

Take a screenshot in Vision mode.

browser_screen_move_mouse

Move the mouse to a position on screen.

browser_screen_click

Click at a position on screen.

browser_screen_drag

Drag the mouse from one position to another.

browser_screen_type

Type text in Vision mode.

browser_wait_for

Wait for text or time in Vision mode.