What Is Playwright MCP? Browser Automation for Claude Code

You just shipped a new checkout flow. Claude built it, it looks right in the code, but you want to actually click through it before calling it done. Normally that means writing a Playwright test, wiring up the test runner, and debugging why the selectors don't match. Or you tab over yourself and click around manually.

There's a better option. lets you tell : "Open my app and check if the checkout flow works." Claude opens a real Chrome window, navigates the app, clicks the buttons, fills in the fields, and reports back what it found. No test code. No setup. Just plain English.

What Is Playwright MCP?

The official Microsoft MCP server for browser control

Playwright MCP is the official MCP server for browser automation — built on the Playwright library, maintained by the Playwright team at Microsoft. This isn't a third-party wrapper or community experiment. It's the same team that built the underlying browser automation library, shipping a first-party integration for AI coding tools.

The package is @playwright/mcp, hosted under the microsoft GitHub organization.

How it fits into Claude Code

MCP — Model Context Protocol — is a standard for giving AI tools access to external capabilities. When you add an MCP server to Claude Code, it adds a set of tools Claude can use. Playwright MCP adds browser tools: navigate, click, fill, screenshot, and more.

If you're not familiar with how MCP servers fit into Claude Code's architecture, the agents and tools article covers the broader picture.

Accessibility tree vs. screenshots

By default, Playwright MCP runs in standard mode: it reads the browser's accessibility tree rather than looking at pixels. The accessibility tree is structured data — element labels, roles, and states — which Claude can parse directly without needing a vision model.

This makes it fast, token-efficient, and compatible with any browser configuration. Claude doesn't "see" the page the way a human does; it reads it the way a screen reader does.

Vision mode also exists. Enable it with the --caps vision flag. In vision mode, Claude works from screenshots and clicks at specific pixel coordinates rather than reading the accessibility tree. It costs more tokens. Standard mode handles the vast majority of real-world tasks — use vision mode only when an element genuinely can't be found through the accessibility tree.

How to Install Playwright MCP

Prerequisites

You need Node.js 18 or later. If you already have Claude Code running, you almost certainly have this covered.

One-command install

claude mcp add playwright npx @playwright/mcp@latest

That's it. Claude Code handles the rest — it registers the server, and Playwright MCP is available the next time you start a session.

Manual config

If you prefer to manage your MCP config directly, the structure looks something like this — exact file location may vary depending on your client:

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

What Can You Do With It?

Navigate and interact

Once installed, you control the browser in plain English. Tell Claude to open a URL, click a button, fill in a form field, or submit. Claude translates that into Playwright actions and executes them against a real browser.

Examples of what you can say:

"Open http://localhost:3000 and sign in with test@example.com / password123"
"Click the Add to Cart button on the first product"
"Fill out the shipping form and go to checkout"

Claude acts on these instructions sequentially, the same way a human would click through the UI.

Take screenshots

At any point during a session, Claude can take a screenshot of the current browser state. This is useful for visual debugging — if something looks wrong or Claude can't find an element, a screenshot gives you (and Claude) a clear picture of what the page actually looks like.

Generate real Playwright test code

This is underused. When you launch Playwright MCP with the --codegen typescript flag, Claude's browser interactions are recorded and output as a real Playwright test file you can run in CI. You describe the flow in plain English, Claude navigates through it, and you get working test code as the output.

It bridges the gap between "AI-assisted exploration" and "production-ready test suite."

Supported browsers

Playwright MCP supports all three Playwright browsers: Chromium (default), Firefox, and WebKit. You switch with the --browser flag.

Useful flags

| Flag | What it does | |---|---| | --headless | Runs the browser with no visible window — faster, good for automation | | --browser | Choose the browser: chrome, firefox, webkit, or msedge | | --isolated | Starts each session with clean state — no cookies, no localStorage | | --viewport-size | Set the browser window dimensions (e.g. 1280x720) | | --device | Emulate a mobile device by name (e.g. iPhone 15) |

Vision Mode vs. Standard Mode

Standard mode is the default and the right starting point. Claude reads the accessibility tree — structured element data — without needing to analyze pixels. It's faster, uses fewer tokens, and works on any page that uses semantic HTML or ARIA labels correctly.

Vision mode is for edge cases. Some UIs use canvas rendering, custom controls, or other patterns that don't expose meaningful accessibility data. In those cases, Claude takes a screenshot and reasons about coordinates instead. It works, but it's slower and more token-hungry.

Start with standard mode. Switch to vision mode only if Claude can't find elements it should be able to find.

Real-World Use Cases

Verify your UI after Claude makes changes

This is the most common beginner use case. Claude finishes building or editing something — a form, a modal, a page layout — and you want to confirm it actually works before moving on. Instead of switching to your browser and clicking around yourself, ask Claude to open the app and walk through it.

Claude will navigate to the right page, interact with the new element, and tell you if anything broke or behaved unexpectedly.

Test a user flow end-to-end

Describe a complete user journey in plain English. "Sign up as a new user, add a product to the cart, go through checkout, and confirm the success page loads." Claude acts like a QA tester — working through every step, noting what succeeded and what didn't.

You don't need to write a test spec. The conversation is the test spec.

Scrape or gather data

For one-off research tasks — grabbing a table of data from a site, checking prices across a few pages, pulling content you'd otherwise copy manually — Playwright MCP can navigate and extract. It's not a production scraping tool, but for occasional tasks it saves significant time.

Build an AI QA engineer (advanced)

At the far end of the use-case spectrum: combine Claude Code with Playwright MCP as a dedicated QA pass. After a feature is built, run a Claude session with a checklist of user scenarios. Claude navigates through each one, screenshots anything that looks wrong, and produces a report. With --codegen typescript, that session can also output a test file for the cases that need to persist in CI.

This is advanced and requires thoughtful prompting, but it's a real workflow some teams use.

Playwright MCP vs. Writing Tests Yourself

| | Playwright MCP | Hand-written tests | |---|---|---| | Setup time | 2 minutes | Varies — can be significant | | Good for | Exploration, one-off checks, verifying changes | CI/CD, regression prevention, team-shared test suites | | Output | Plain-English report | Runnable test files | | Maintenance | None | Tests need updating when UI changes |

The two aren't in competition. Playwright MCP is for exploration and quick verification. Hand-written tests are for systematic, automated regression coverage. They work well together — especially with --codegen typescript turning MCP sessions into test file starting points.

Should You Add This to Claude Code?

Add it if any of these apply:

You want to verify UI changes without switching context. Claude makes edits and immediately checks they work — you never leave the terminal.
You want end-to-end test coverage but not the overhead of writing tests from scratch. Use MCP to explore the flow, then export with --codegen to get test code.
You build web apps and regularly do manual click-through testing. That manual work is exactly what Playwright MCP replaces.

It takes about 2 minutes to install. There's no extra cost beyond your normal Claude usage — Playwright MCP just adds browser tools to the session. And the first time you watch Claude open a real browser and click through your app on its own, it's genuinely impressive.

For more on how MCP tools fit into Claude Code's capabilities, read What Are Claude Code Agents?. If you're interested in automating other parts of your workflow, Claude Code Hooks handle the non-browser side — automatic formatting, test runs, and notifications triggered by Claude's actions. And if you're still evaluating tools overall, Best Free AI Coding Tools 2026 has the full picture.