Playwright MCP: let agents use a browser via accessibility snapshots instead of screenshots
TL;DR
Playwright MCP exposes browser tools driven by the accessibility tree: faster, cheaper in tokens and more reliable than screenshot-based control. Add it to Claude Code with claude mcp add playwright npx @playwright/mcp@latest. Great for E2E tests, bug reproduction and responsive checks.
When you want an agent to test a sign-up flow, reproduce a UI bug or fill forms in bulk, the “classic” way is to show it screenshots and let it guess coordinates — slow, token-hungry and error-prone. Microsoft’s Playwright MCP works differently: the agent reads the page through the accessibility tree — structured data describing buttons, inputs, links and their roles — and acts on that. No vision model required; faster and more reliable.
Why accessibility snapshots beat screenshots
| Criterion | Screenshot-based | Accessibility snapshot |
|---|---|---|
| How the page is “seen” | Pixels, guessed coordinates | A tree of elements with names, roles and states |
| Reliability | Breaks when layout or screen size changes | Precise element references |
| Model requirement | Needs vision | Only reads structured text |
| Side benefit | — | Exposes accessibility bugs (unlabelled buttons…) |
Adding it to Claude Code
# For all projects
claude mcp add --scope user playwright -- npx -y @playwright/mcp@latest
# Current project only (writes .mcp.json, which you can commit)
claude mcp add --scope project playwright -- npx -y @playwright/mcp@latestRequires Node.js 18+. After adding it, run /mcp to confirm the server is connected. Claude Desktop, VS Code and Cursor use an equivalent JSON entry running npx @playwright/mcp@latest.
Useful flags
| Flag | Effect |
|---|---|
--headless | Run without a window (headed by default so you can watch) |
--isolated | In-memory profile, nothing saved to disk — run several clients in parallel |
--browser | Pick the browser/channel (chrome, firefox, webkit, msedge…) |
--storage-state | Load login state (cookies, localStorage) from a file — use with test accounts |
--allowed-origins / --blocked-origins | Restrict which domains the browser may visit |
--caps vision,pdf,devtools | Extra capabilities: coordinate-based actions, PDF export, devtools |
--save-trace, --output-dir | Save Playwright traces and output files for later debugging |
--viewport-size | Set the viewport size — for responsive checks |
Note: with a persistent profile only one browser process can use it at a time — add --isolated for parallel runs. The project is still at 0.0.x, so pin a version and test before relying on it.
Sample QA prompts
Open http://localhost:3000, sign up with the test account in fixtures/users.json,
add two products to the cart and check the total. If it's wrong, take a screenshot
and write the reproduction steps to bug-report.md.Open /checkout at a 375x812 viewport. List buttons without an accessible
name and inputs without labels.When to use it — and when not to
| Good fit | Poor fit |
|---|---|
| Exploratory testing, bug reproduction | High-volume coding agents with tight token budgets |
| Long agent loops that need persistent browser state | Simple one-off browser tasks |
| Form filling and data entry without vision models | Pixel-based interaction (canvas, games) |
Accessibility trees and tool schemas are verbose, so for token-sensitive coding agents Microsoft’s own guidance leans towards Playwright CLI + skills; the trade-off is losing MCP’s persistent browser state and rich introspection.
Safety notes
- The server runs with your user permissions; browsers it launches can reach your network and file system.
- Use it on dev/staging with test accounts; never hand the agent real passwords.
- Pages the agent opens are untrusted content — they may contain prompt injection. Restrict domains with
--allowed-origins. - Remove or disable the server when you don’t want browser automation in every session.
How to apply it
- Developers: Use it to reproduce bugs from QA descriptions; once the agent finds the right flow, ask it to turn that into a fixed Playwright test for CI — don’t make your tests depend on an agent.
- QA: Exploratory testing from natural-language scenarios, with free accessibility checks from the snapshots.
- PMs: A one-sentence smoke test of staging before a demo, instead of waiting for someone to click through manually.
Sources & references
- microsoft/playwright-mcp — GitHub
- Playwright MCP — dev.co
- Try an MCP: Playwright — Dometrain AI Workshop