Home / Blog / Playwright MCP server

The Playwright MCP server: what it drives, and what it leaves behind

Updated 1 September 2026 · Playwright 1.62

Most people meet this tool by pasting a config block somebody posted in a channel and watching a browser open. This page is about what that block started and where its output goes.

Everything below was checked against Playwright 1.62 on 1 September 2026, and every command was run on 1.62.1. Dates matter more here than anywhere else in the framework: the documentation and the shipped binary already disagree about several flag and tool names, and both are moving. Run --help on your own install before you trust a name here, and read the capabilities page beside it, because those two do not agree either.

What is the Playwright MCP server?

MCP is a protocol an LLM client uses to call tools, so an MCP server is the thing that turns "click the submit button" into a real browser doing it. Playwright MCP is Microsoft's implementation of that for a browser: repository github.com/microsoft/playwright-mcp, package @playwright/mcp, whose package.json gives the author as Microsoft Corporation.

What changed in 1.62 is one bullet in the release notes, under New APIs → Command line & MCP: "Playwright now bundles the Playwright MCP server and playwright-cli, runnable via npx playwright mcp and npx playwright cli." Keep the version attached to that sentence, because it is false about 1.61.

The package is older than the bundling. The 1.59 release notes already name @playwright/mcp beside browser.bind(), as one of the clients that can attach to a launched browser. So 1.62 is the release where you stopped having to install it separately, which is a smaller change than "1.62 shipped MCP" makes it sound. If you are on 1.62 you already have it, and the bundled server reports the version of the framework it came in.

$ npx playwright --version
Version 1.62.1
$ npx playwright mcp --version
Version 1.62.1

Playwright 1.62.1 · shell, on Windows · 1 September 2026

Is it Microsoft's? Which server did you install?

Microsoft's is @playwright/mcp, at github.com/microsoft/playwright-mcp: the one the documentation on playwright.dev/mcp/ describes, and the one npx playwright mcp starts.

There is at least one other server with the same name. @executeautomation/playwright-mcp-server lives at github.com/executeautomation/mcp-playwright, its package.json names ExecuteAutomation, Ltd as the author, and its README's first heading is Playwright MCP Server. It answered on 1 September 2026. We have not run it and say nothing here about how well it works; they are two different packages, and someone searching the phrase at the top of this page will meet both.

The check is one line of your own config. Open it and read the package name inside args. The label above that, under mcpServers, is whatever the person who wrote the block typed, and in Microsoft's own example it is the word playwright.

How do you run it?

On 1.62 the short route is npx playwright mcp, which starts the server on standard input and output and waits for a client. The other route is the config block, which is what an MCP client wants and what almost every posted snippet is.

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

JSON · the block printed on playwright.dev/mcp/installation · parsed clean on 1 September 2026

That block is the first sample here, and like every fragment on this page it was written against Playwright 1.62 and run on 1.62.1. Note what it fetches. @playwright/mcp@latest is the standalone package, on its own version line and at 0.0.80 on npm today, while npx playwright mcp uses the copy inside your Playwright install. Those are not the same build, and the difference shows up in the tool list.

The documented prerequisite is Node.js 20 or newer, an MCP client has to be pointed at the server, and the browsers download on first use. The repository README and the package's own engines field both say Node 18, so if you are on 18 and it works, that is the documentation being stricter than the package.

The docs carry a config block each for VS Code, Cursor, Claude Code and Claude Desktop at docs/getting-started-mcp, under a fifth heading for everything else, and copying four of those in here would only date faster than they do. If you do not have Playwright installed at all, start with getting a first suite running by hand.

The browser then opens headed, on purpose, so you can watch it, which is delightful on a laptop and useless on a build agent. --headless turns it off, and the binary's own help says as much: "run browser in headless mode, headed by default".

What can the agent see, and what can it miss?

Every tool that touches the page answers with an accessibility-tree snapshot. Here is one, from the bundled 1.62.1 server pointed at the demo application Playwright's own documentation uses.

- generic [ref=e1]:
  - generic [ref=e2]:
    - text: This is just a demo of TodoMVC for testing, not the
    - link "real TodoMVC app." [ref=e3] [cursor=pointer]:
      - /url: https://todomvc.com/
  - generic [ref=e6]:
    - heading "todos" [level=1] [ref=e7]
    - textbox "What needs to be done?" [active] [ref=e8]

Playwright 1.62.1 · browser_snapshot against demo.playwright.dev/todomvc · trimmed after the input

There are no pixels in that and no coordinates. Each interactive element carries a short reference, and the agent acts by quoting it back: browser_type { ref: "e8", text: "Buy groceries" }. The refs are stable inside a single snapshot and invalidated by the next page change, so the loop is navigate, snapshot, act, snapshot again.

So the agent sees what the accessibility tree exposes. The documentation raises the two hard cases itself: a gear icon with no accessible name, and a canvas. This is the same discipline that decides whether getByRole resolves in an ordinary test.

Vision mode is the way out: switch on the vision capability and six coordinate-based mouse tools appear, driven from screenshots. Microsoft's own guidance is that for most web applications the snapshot default is more reliable and more token-efficient, and that vision mode is for the cases the accessibility tree does not cover.

None of which tells you anything about accessibility conformance. It is a machine-readable view of the page, and one that snapshots cleanly can still be unusable.

Which tools does it give the agent?

The documentation groups the tools two different ways, and they do not line up. playwright.dev/mcp/introduction sorts them into core, network and storage, testing and debugging, and vision as an option. playwright.dev/mcp/capabilities sorts them by the flag that switches them on: core, which it says is always enabled and cannot be disabled, plus network, storage, testing, vision, pdf, devtools and config. Both are true. A tool can sit under Testing & Debugging on the first page and inside core on the second, which browser_evaluate does.

So we asked the servers. A tools/list call over stdio answers for your install.

The default is 24 tools, on both servers. The introduction page advertises "40+ tools covering navigation, forms, network mocking, storage, tracing, video, and more", which is accurate about the product and not about a default install. Everything past the twenty-fourth arrives when a capability is switched on.

Both binaries under-report what the flag takes. This is the block the documentation gives for switching a capability on, one line different from the one above.

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

JSON · the block printed on playwright.dev/mcp/vision-mode · parsed clean on 1 September 2026

--help on both binaries gives --caps three possible values: vision, pdf and devtools. The capabilities page documents eight, those three plus core, network, storage, testing and config. Handed the three from --help, the bundled server answered tools/list with 42 tools and no browser_generate_locator. The six documented names other than core, which is always on and cannot be switched off, took the same install to 68. The same six through the PLAYWRIGHT_MCP_CAPS environment variable and through the documented config file also came back at 68, so all three routes reach the same list.

An unrecognised capability name is accepted in silence. --caps=testing,bogus started the server, printed no warning, and returned the same 29 tools that testing alone returns. A misspelled name costs you the tools it would have brought and produces no error. If a capability is switched on and its tool is still missing, check the spelling of every name in the list first.

The shipped names are not all the documented names. The capabilities page lists 21 tools under core; 20 of those 21 were in the 24 that answered. The missing one is browser_run_code, which ships as browser_run_code_unsafe. Three tools answered that the page does not list at all: browser_drop, browser_network_request and browser_find, the last of which searches the snapshot for a string and hands back the matching nodes with their refs.

The testing tools are not in the default. browser_generate_locator and the four browser_verify_* assertions belong to the testing capability. On this install, --caps=testing took the list from 24 to 29 and they appeared.

There is no point reprinting the tool tables here; the documentation has them and they will change again. Run --help, and ask the server for a tools/list. Both answer for the build in front of you.

Playwright MCP or playwright-cli?

They arrived in the same release-note bullet and they do different jobs. MCP is a server: the model calls tools with structured parameters and gets snapshots back. playwright-cli is a command surface: the agent runs shell commands and reads the output.

Microsoft compares its own two products on five axes: what each is best for, how the agent talks to it, what it costs in context, whether it starts headed or headless, and how it is set up. It scores MCP's token cost higher, because the tool schemas and the snapshots both sit in the conversation. Fair comparison, and it is still the vendor holding both products.

Our line follows from where the agent already lives. An agent working through shell commands inside a large repository wants the CLI, which fits how it already operates. An agent whose whole job for the next twenty minutes is a browser wants the server, which keeps the page state between calls. Both packages version independently of the framework and of each other, at 0.0.80 and 0.1.18 on npm today, and neither number is 1.62.

What a long session costs, and what it leaves on disk

Per snapshot it is cheap. The introduction page puts a snapshot at "~200-400 tokens per snapshot vs thousands for DOM/screenshots", and the snapshots page puts a screenshot read by a vision model at roughly 3,000 to 5,000.

Per session it accumulates, for two structural reasons: nearly every tool call returns a fresh snapshot, and the tool schemas stay in the context for the whole conversation. That is why Microsoft's own table scores MCP above the CLI on token cost. Multiplying a snapshot figure by a number of steps would produce a number nobody measured, so this page does not.

The disk side is not in the documentation at all. On the run above, browser_navigate did not return the snapshot inline. It wrote it to .playwright-mcp\page-2026-09-01T11-38-34-409Z.yml and returned a link to that file, alongside a console log written next to it. browser_snapshot, asked directly, returned the tree in the response. A session therefore leaves a directory of YAML and logs in your working folder, so check your ignore rules before an agent runs somewhere you commit from.

Login state and cookies are preserved between sessions by default, so an agent pointed at an environment where being logged in matters will still be logged in next time. Switching on the devtools capability adds browser_start_tracing, which produces the artifact you open afterwards to find out what a run did: the Playwright trace, and how to read one covers what is in it.

We do not sell security work, so this page states the posture once and stops: the microsoft/playwright-mcp README says plainly that Playwright MCP is not a security boundary.

An agent driving a browser is not a test

A test is a file in your repository that CI runs tomorrow morning without anybody asking it to. An MCP session is a thing that happened. It ends, the browser closes, and the YAML in .playwright-mcp/ describes one afternoon.

Take the evidence from one page. playwright.dev/mcp/tools/assertions documents the testing capability, and it was read twice for this article: once as the rendered page, once as its MDX source in the playwright.dev repository. No tool on it writes a test file. The nearest one is browser_generate_locator, described there as: "Generate a Playwright locator for an element, useful when converting exploratory automation into test files." The conversion is that sentence's own subject, and no tool performs it. The assembled spec printed further down is introduced with "The generated code can be assembled into a Playwright test:" — and somebody does the assembling.

Here is exactly how far the tool goes, run against the demo application. Note the parameter name: the shipped tool takes target where the documentation's table shows ref.

→ browser_generate_locator { target: "e8", element: "todo input" }

### Result
getByRole('textbox', { name: 'What needs to be done?' })

Playwright 1.62.1 · PLAYWRIGHT_MCP_CAPS=testing · the reply as the server returned it

That is a string. A person still has to put it in a file, decide what the test asserts about it, name the promise being guarded, and get it running on every commit. Whether the file that person ends up with can be trusted when a machine drafted it is a separate question about generated tests.

That does not make the tool small. Exploration is what it is good at: finding out how a flow behaves, what is on the page, which locator will hold, and browser_generate_locator exists precisely to carry that back to whoever writes the file. Reproduction is the other one, driving a reported bug once, live, in a real browser, while you watch.

Everything past that is the part somebody owns. A suite build hands over the job that runs the suite on every commit, with the reporter and the trace wired up — the artifact an exploratory session cannot leave behind, however good it was.

These tools drive browsers and nothing else, so a native iOS or Android application is outside what any of them can reach, and none of them is a load or a security tool.

Questions