Skip to main content

Published

Playwright MCP: What It Is, Setup, and Where It Fits (2026)

Short answer

Playwright MCP is Microsoft's Model Context Protocol server that lets an AI agent control a real browser through Playwright. It sends the model a structured accessibility snapshot of the page instead of screenshots, so the agent can click, type and navigate without a vision model. It is excellent for exploring an app and for drafting a test. It does not decide which tests matter or whether the ones you already have are any good.

Last updated: 2026-11-07

What is Playwright MCP?​

Playwright MCP is an open source server from the Playwright team, published as the @playwright/mcp npm package. It speaks the Model Context Protocol, so any MCP client (Claude Code, Claude Desktop, Cursor, VS Code, Windsurf and others) can call it as a set of browser tools.

Its main design choice is that it works from the page's accessibility tree. Each time the agent asks for a snapshot, it gets a text outline of roles, names and states, with a reference for every element. The model then says "click the element with this reference" instead of guessing pixel coordinates. The project README lists three benefits: it is fast and lightweight, it needs no vision model, and tool application is deterministic because there is no screenshot ambiguity.

Node.js 18 or newer is required, per the README.

How do I set up Playwright MCP?​

The standard configuration works in most MCP clients:

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

In Claude Code you can add it from the command line:

claude mcp add playwright npx @playwright/mcp@latest

After that, ask the agent to open your local app and do something. A prompt like "open http://localhost:3000, sign up with a new email, and tell me what the dashboard shows" is enough to confirm the tools are wired up.

Which options matter most?​

The server takes command-line flags, and each has an environment variable twin. These are the ones teams reach for first:

FlagWhat it does
--browserPick chrome, firefox, webkit or msedge
--headlessRun without a window (headed is the default)
--isolatedKeep the browser profile in memory and do not save it to disk
--user-data-dirPoint at a persistent profile directory
--storage-stateLoad a saved storage state file for isolated sessions
--capsEnable extra capabilities such as vision, pdf and devtools
--extensionConnect to a running Edge or Chrome through the Playwright browser extension
--test-id-attributeSet the attribute used for test ids (default data-testid)

By default the server uses a persistent profile, like a regular browser, so logins stick between sessions. For anything that looks like testing, prefer --isolated plus a storage state so each run starts clean.

What can the agent do with it?​

The tool set covers what you would do by hand in a browser: navigate, snapshot the page, click, type, fill forms, select options, manage tabs, take screenshots, and inspect network requests. Two tools are worth knowing by name. browser_snapshot returns the accessibility snapshot and is the one the agent should use for most actions. browser_take_screenshot exists for when you need a picture, and coordinate-based mouse tools need the vision capability.

That makes it a good fit for four jobs:

  1. Exploring a feature you just built. The agent walks the flow and reports what it saw.
  2. Reproducing a bug. Describe the steps and let the agent hit them in a real browser.
  3. Drafting a Playwright test. The agent learns the page structure first, then writes a test against real element names instead of invented selectors.
  4. Debugging a failing test. Point the agent at the failing page and let it look.

Playwright MCP or Playwright CLI?​

The README itself raises this question. Its position is that coding agents increasingly prefer CLI workflows exposed as skills, because CLI calls are more token-efficient: they avoid loading large tool schemas and long accessibility trees into the model's context. MCP stays relevant, according to the same README, for specialized loops that benefit from persistent state and rich introspection, such as exploratory automation, self-healing tests, and long-running autonomous workflows.

A practical rule: if your agent is mostly editing code and occasionally checking the browser, try the CLI route first. If the agent is the one doing the exploring, MCP's persistent browser context is useful.

What Playwright MCP does not do​

Playwright MCP gives an agent a browser. It does not give the agent a view of your testing posture, and teams with coding agents get surprised by that gap. Claude or Cursor can write your tests well. The open questions sit around the tests:

  • Which tests exist, and which were ever reviewed? An agent that drafts a test through MCP can mark it green. Nobody has to have read it.
  • What is actually covered? Each session sees one path. MCP does not aggregate what real users do against what your suite exercises.
  • What drifted? When the product changes, nothing tells the agent which older tests no longer match the requirement.
  • What should be tested next? An agent only tests what it is asked to test.

All four need a layer above the browser tool.

Where TestChimp sits relative to Playwright MCP​

Keep using Playwright MCP, since it is a good way for an agent to touch the real app. TestChimp adds the layer that gives the agent and your team the posture picture: scenarios written in Markdown in your repo, the tests linked to them, coverage that shows what is and is not exercised, and Verified Tests so a named person confirms what an agent-written test checks. It also exposes its own MCP surface, so a coding agent can ask what to test next and report back what it changed.

The loop looks like this: the agent uses Playwright MCP to explore and draft, TestChimp records which scenario each test serves and flags agent-edited tests for human review, and the next prompt to the agent starts from the gaps instead of a blank page. For the review half of that loop, see How to trust AI-written tests and How do I get humans to review tests my coding agent wrote?.

TrueCoverage, which compares what users do in production with what your tests cover, is available on the Growth plan or during the trial.

A safe way to run Playwright MCP in a test workflow​

  1. Use --isolated. A fresh in-memory profile keeps one run from leaking into the next.
  2. Seed test data through your API, not through the agent's clicks. Agents are slow and inconsistent at setup. See Backend asserts vs UI assertions.
  3. Ask the agent to write the result down as a Playwright test, then run it without the agent so the test file is what you keep.
  4. Link the test to a scenario so coverage and review attach to a written requirement.
  5. Have a person read the test before you trust the green run.

Frequently asked questions

What is Playwright MCP?

Playwright MCP is a Model Context Protocol server from the Playwright team, installed from the @playwright/mcp npm package. It lets an AI agent drive a real browser using structured accessibility snapshots of the page instead of screenshots.

How do I add Playwright MCP to Claude Code?

Run claude mcp add playwright npx @playwright/mcp@latest. Other MCP clients use the standard JSON config with npx and the @playwright/mcp@latest argument. Node.js 18 or newer is required.

Does Playwright MCP need a vision model?

No. By default it works from accessibility snapshots, which are text. A vision capability can be enabled with the --caps flag for coordinate-based interaction.

Is Playwright MCP the same as Playwright Test?

No. Playwright Test is the test runner you execute in CI. Playwright MCP is a server that lets an agent operate a browser interactively. An agent can use MCP to explore a page and then write a Playwright test you run without it.

Should I use Playwright MCP or the Playwright CLI with skills?

The Playwright MCP README says coding agents increasingly favor the CLI because it uses fewer tokens, and that MCP suits loops that need persistent browser state, such as exploratory automation or self-healing tests.

Does Playwright MCP tell me which tests matter?

No. It operates a browser. Knowing which scenarios are covered, which tests a human reviewed, and what to test next needs a posture layer such as TestChimp on top of the browser tool.

Give your coding agent a posture view, not only a browser

Keep Playwright MCP for exploring. Use TestChimp to link tests to scenarios, see coverage, and flag agent-edited tests for review. 14-day free trial, no credit card.

Start a 14-day free trial · Book a demo