Playwright MCP

Official MCP server by Microsoft for browser automation built on Playwright.

Description

Playwright MCP is a Model Context Protocol server that provides browser automation via Playwright. It is maintained by Microsoft in the microsoft/playwright-mcp repository.

Unlike approaches that analyse screenshots, the server works on the page's accessibility tree. The model therefore receives a structured representation of the page instead of an image.

According to the documentation, its feature set includes:

Navigating, clicking, typing, hovering, drag-and-drop, file uploads, form filling, keyboard input, screenshots, snapshots and handling dialogs. Also tab management, recording and mocking network requests including an offline mode, access to cookies, localStorage and sessionStorage, video and trace recording, code generation, coordinate-based mouse actions, PDF output, and assertions for tests.

It requires Node.js 18 or newer. The server runs directly via npx without any prior installation:

Code
npx @playwright/mcp@latest

In an MCP client, it is registered through the usual configuration file:

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

The documentation covers setup for a range of clients, including Codex, Claude Code, Cursor, VS Code, Copilot, Cline, Gemini CLI, LM Studio, Warp and Windsurf.

Why the accessibility tree instead of screenshots

Many AI browser automation tools rely on screenshots: the model receives an image of the page and has to guess pixel coordinates for clicks. Per the documentation, Playwright MCP takes the opposite approach and works with the accessibility tree — the same structured representation screen readers use. The model receives named elements such as buttons, links, and form fields instead of pixels, which makes clicks and input noticeably more reliable and uses fewer tokens than an image. Screenshots remain available as an additional tool, for example for visual verification, but they are not the primary basis for control.

Operating modes: stdio, HTTP, and Docker

For most MCP clients, Playwright MCP runs as a local stdio process launched directly via npx, requiring no open network connection. For scenarios where multiple clients should share the same server or the server runs on a different machine, a standalone HTTP endpoint can be started instead, which clients address via a URL. For container use, the project provides a Docker image; the documentation explicitly notes that only headless Chromium is currently supported inside the container, while locally Chrome, Firefox, WebKit, and Edge can also run with a visible window.

Who Playwright MCP fits

The server suits anyone who wants an AI agent to operate real web interfaces: end-to-end tests driven from a description instead of fixed test code, recurring data collection from websites without an official API, filling in multi-step forms, or automatically checking whether a page still behaves as expected after a change. Thanks to the accessibility-tree approach, Playwright MCP is also well suited for accessibility checks, since it evaluates exactly the structure assistive technologies see. For plain content retrieval without interaction, a simpler fetch server is often the lighter choice since no browser process needs to start.

Frequently asked questions

Does Playwright MCP need a separate browser installation? No, the required browsers are managed by Playwright itself and downloaded automatically when needed. Does the server work without a visible screen? Yes, it also runs headless on servers without a graphical interface; for Docker, only headless operation is currently supported anyway. Does login state persist between sessions? In the default profile, yes; in isolated mode, session state is discarded on close.

Requirements

Node.js 18 or newer and an MCP client. A headed browser needs a graphical session in the runtime environment; alternatively, the server can run headless or as a standalone HTTP service.

Installation instructions

Playwright MCP exposes browser automation as MCP tools. Setup needs no prior installation: the server is launched via npx, which downloads it on the fly.

Quick start

Start the server directly through npx and add the command to the client's MCP configuration. A global installation is not required.

For a standalone local HTTP endpoint, start the server with --port 8931 and configure http://localhost:8931/mcp as the client URL. For reproducible installations, pin the version shown below instead of using @latest.

Step 1: Requirement for Playwright MCP

Node.js 18 or newer. Check your version with:

Code
node --version

Step 2: Registering Playwright MCP with your client

MCP clients read their servers from a JSON configuration. The entry for Playwright MCP looks like this:

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

Where this file lives differs by client. The official repository documents setup for, among others, Codex, Claude Code, Cursor, VS Code, Copilot, Cline, Gemini CLI, LM Studio, Warp and Windsurf.

Step 3: Running Playwright MCP without a client

To try it out, you can also run the server directly:

Code
npx @playwright/mcp@latest

On first run, npx downloads the @playwright/mcp package. After that, the server is ready and the client can use its tools.

Playwright MCP in Docker

For container use, the documentation notes that only headless Chromium is currently supported.

Common sources of error

If the client offers no Playwright tools after configuration, it's usually a malformed JSON structure in the MCP configuration file — a missing comma or bracket is enough for the entire entry to be ignored. A second common pitfall is an outdated Node.js version; node --version should show at least 18, otherwise the npx call fails or the server starts with errors. In headless environments without a graphical interface (such as a server), the default mode with a visible browser doesn't work — starting with an additional headless flag solves that.

bash
node --version

Step 4: Verifying the setup

After restarting the client, check whether the connection works with a simple task, such as "Open the homepage of example.com and describe what you see." If the agent responds with a description of the actual page instead of an error message, the server is set up correctly. For debugging purposes, a trace can additionally be recorded that shows in detail which actions the agent performed in the browser.

For production automation

Anyone using Playwright MCP long-term for tests or recurring automation should consider an isolated browser profile so that login credentials and session state aren't accidentally shared between tasks. For CI/CD pipelines, headless mode combined with Docker is the best fit, since no graphical interface is available there anyway.

Running multiple browser instances in parallel

Anyone running several independent automation tasks at once should start a separate server instance with its own port for each task, rather than sharing one instance. This prevents parallel tasks from closing each other's tabs or overwriting state.

This becomes especially important in CI pipelines running multiple jobs concurrently, where a shared instance can otherwise cause hard-to-diagnose flaky test failures.

Source: github.com/microsoft/playwright-mcp, checked on 2026-09-02.

npx @playwright/mcp@latest

Authentication

The local stdio server does not require its own login. Authentication to visited websites uses the browser profile, imported storage state, or browser extension. An HTTP endpoint has no built-in user login and must be protected separately when exposed over a network.

Required access permissions

Requires network access to the automated websites and permission to launch a browser process. File uploads and output are restricted to MCP roots or the current working directory by default. Additional browser permissions such as clipboard or geolocation are granted only through --grant-permissions.

Transmitted or stored data

The server processes page content as accessibility snapshots and, depending on enabled tools, screenshots, console and network data, form values, downloads, videos, and traces. The default profile keeps cookies, localStorage, sessionStorage, and login state locally; isolated mode discards session state when closed. HTTP, proxy, or CDP operation may route this data through additional systems.

Security risks

Web pages can contain malicious or misleading instructions. With an authenticated browser session, an agent can perform real actions, read confidential content, or upload data. Persistent profiles and saved traces may contain session tokens or personal data. Allow only required hosts, roots, and browser permissions; use isolated profiles for sensitive work; and never expose HTTP endpoints without protection.

License and costs

License
Apache-2.0
Cost
free

The open-source server has no license fee. Costs may arise only from your runtime environment, proxies, or paid target systems.

Alternatives

At a glance

Provider
Microsoft
Status
Official server
Deployment
Local and remote
Current version
0.0.80
GitHub stars
39,698
Last reviewed
07.09.2026

Repository and documentation

Categories

Supported clients

Related guides

Guides and background related to this entry.

No related guides yet.