Playwright MCP: what it does and where it fits

What is Playwright MCP?

The Model Context Protocol is a standard way to hand an AI assistant a set of tools it can call. An MCP server publishes those tools; an MCP-capable client, such as Claude Code, Copilot, Cursor or VS Code, calls them on the model's behalf.

Playwright MCP publishes browser tools. Once it is connected, the assistant can open a page, read its structure, fill a form, click a button and wait for something to happen, using Playwright underneath. The practical difference from ordinary prompting is that the model is no longer guessing what a page contains. It can look.

It is worth being clear about the maturity. The package is @playwright/mcp, it was first published in March 2025, and the current release is 0.0.79. That is 432 published versions in about eighteen months, and it is still on a 0.x version number. Expect the tool surface to move.

Why the accessibility tree matters

The interesting design decision is what the agent is shown. Playwright MCP does not send screenshots for the model to interpret. It sends the page's accessibility tree, which the project describes as using "Playwright's accessibility tree, not pixel-based input", so that it needs "no vision models" and "operates purely on structured data".

That has three consequences that matter in practice:

• Targets are references, not coordinates. The agent clicks an element it found in a snapshot, rather than a point it estimated from an image. The project's claim is "deterministic tool application" that "avoids ambiguity common to screenshot-based approaches", and that is the honest reason these agents are less flaky than the vision-driven generation.
• It is cheaper and faster. No image encoding, no vision model.
• It inherits the accessibility tree's blind spots. If your app renders interactive things as unlabelled divs with click handlers, the tree is a poor description of your UI, and the agent will struggle exactly where a screen-reader user would. This is a real constraint on legacy or canvas-heavy applications.

Screenshots are still available, but the README is explicit that they are advisory: you "can't perform actions based on screenshot", and interaction goes through browser_snapshot. Treat images as something to show a human, not something the agent acts on.

Installing and configuring it

It needs Node.js 18 or newer and an MCP-capable client. The baseline configuration is the same everywhere:

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

Most clients have a one-line equivalent:

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

It can also run over HTTP rather than stdio, which is what you want if the agent and the browser are not on the same machine:

npx @playwright/mcp@latest --port 8931

The server is then reachable at http://localhost:8931/mcp.

The flag most people want first

By default the browser uses a persistent profile, and only one browser instance can hold it at a time. That is convenient until you run two things at once, at which point it is the first thing that breaks. --isolated gives every session a fresh profile and throws away its storage at the end:

npx @playwright/mcp@latest --isolated --storage-state=auth.json

Pairing it with --storage-state is the usual way to start from a logged-in state without letting the agent accumulate cookies across runs. --browser selects the engine and accepts chrome, firefox, webkit or msedge.

What the tools actually are

The core set is small and readable, which is a good sign in an MCP server. The ones you will see the agent use constantly:

• browser_navigate to go to a URL
• browser_snapshot to read the accessibility tree, which is what everything else references
• browser_click, browser_type and browser_fill_form to interact
• browser_find to locate an element
• browser_wait_for to wait on a condition
• browser_evaluate to run JavaScript in the page
• browser_tabs to manage tabs, and browser_take_screenshot for a picture to show a human

The shape to notice is that browser_snapshot comes first and everything else refers back to it. An agent that has not snapshotted recently is working from a stale idea of the page, which is the most common cause of an agent confidently clicking the wrong thing.

Optional capabilities

Anything beyond core automation is off by default and enabled with --caps. This is a sensible default, because every extra tool is extra schema in the model's context.

• --caps=vision adds coordinate-based tools such as browser_mouse_click_xy, for the cases the accessibility tree cannot express
• --caps=testing adds assertions such as browser_verify_text_visible
• --caps=network adds request interception, browser_route_list and browser_unroute
• --caps=storage adds cookie, localStorage and sessionStorage tools
• --caps=devtools adds tracing, video and browser_highlight
• --caps=pdf and --caps=config cover the remaining cases

If you are using this to explore an application rather than to write tests, --caps=testing is the one that changes the experience most, because it lets the agent state and check an expectation rather than just describing what it saw.

When to use it, and when not to

Microsoft's own README is unusually candid here, and it is worth repeating because most write-ups skip it. For coding agents it suggests the Playwright CLI may be the better path, because CLI calls are "more token-efficient" and avoid "loading large tool schemas verbose accessibility trees into model context".

In other words, MCP is not automatically the right choice. The cases it recommends MCP for are the ones where the browser context has to persist across many steps: exploratory work, self-healing tests, and long-running autonomous sessions where "persistent state, rich introspection, iterative reasoning over page structure" earn back the token cost.

A reasonable rule of thumb:

• Use Playwright MCP when you want the agent to explore an app it has not seen, reproduce a bug interactively, or work out why a selector broke.
• Use the Playwright CLI or plain code when you already know what the test should do and you want it written, committed and run in CI. Generating a spec file is a code task, not a browsing task.

Limits worth knowing before you rely on it

It is not a security boundary

The project states plainly that Playwright MCP is "not a security boundary", and that flags such as --allowed-origins do "not serve as a security boundary" either. An agent driving a browser with your session cookies can do anything you can do in that browser. Point it at throwaway accounts and non-production data, and do not treat an origin allowlist as containment.

It is pre-1.0

At 0.0.79 across 432 releases, tool names and flags are still moving. That is fine for interactive use and a poor foundation for something load-bearing in CI without pinning the version.

Structure in, structure out

As above: an application whose interactive elements are not exposed to the accessibility tree gives the agent very little to work with. If you are evaluating this and it performs badly on your app, check the accessibility tree before blaming the model.

Playwright MCP and a browser grid

Playwright MCP drives one browser, usually locally. That is the right shape for exploring and debugging, and the wrong shape for the question tests exist to answer, which is whether the application works across the browsers and devices your users actually have.

The two fit together in sequence rather than competing. Use an agent to explore the feature and work out what the test should assert, commit the resulting Playwright spec, then run that spec across browsers on a grid. TestingBot runs Playwright on real browsers and on real mobile devices, in parallel, which is where the wall-clock saving comes from once a suite is more than a handful of specs.

If you want to size that, the parallel calculator is the quickest way to see what a given level of concurrency does to your run time.

How this differs from the TestingBot MCP server

These two get confused constantly because they share an acronym, so it is worth stating the difference precisely.

• Playwright MCP drives a browser. Navigate, click, type, snapshot. Its scope is one page at a time.
• The TestingBot MCP server drives the TestingBot platform. Its 48 tools cover listing available browsers and real devices, uploading an app, starting an App Automate or Maestro run, polling it, pulling results and failure logs, starting live sessions, and managing storage, tunnels and team settings.

One important thing ours does not do, because the category is full of claims like this: it does not write your tests. There is no tool in it that generates, authors or repairs test code. It is a control and observability plane over the platform.

Used together, an assistant can explore a feature with Playwright MCP, and then use the TestingBot MCP server to run the resulting suite across a real device fleet and tell you what failed. The TestingBot MCP documentation covers setup, and there is a full tool reference if you want to see exactly what is exposed before installing anything.

Related reading

• Using ChatGPT to write and interpret automated tests
• Playwright Codegen: recording tests in VS Code
• AI testing tools compared
• Visual testing with Playwright