Playwright MCP Explained: Setup, Config & Real-World Examples (2026)

Playwright MCP lets AI control a real browser. Not a simulated one.

It reads the page through the accessibility tree, the same semantic structure screen readers use, and returns structured data instead of screenshots. That single design decision is what separates Playwright MCP from every vision-based automation tool on the market right now.

If you've been writing Playwright tests manually, translating test cases into selectors, waits, and assertions by hand, Playwright MCP changes the workflow. You describe what to test in plain English. The AI opens a real browser, interacts with your app, and generates working Playwright code from actual page state.

This guide covers what Playwright MCP is, how it works (including the 2 operating modes most guides skip), how to set it up across every major IDE, and what changed in the 2026 updates that shifted the entire Playwright AI ecosystem. We also compare it to the newer Playwright CLI, so you can pick the right tool for your setup.

Last updated: March 2026 | Tested with Playwright MCP v0.0.68

New in 2026: Microsoft now recommends Playwright CLI over MCP for coding agents. CLI uses 4x fewer tokens per session. This guide covers both so you can pick the right one. Jump to the MCP vs CLI comparison.

What is Playwright MCP?

The Playwright MCP server is a lightweight local service that exposes Playwright's browser automation as callable tools through the Model Context Protocol.

MCP, or Model Context Protocol, is an open standard created by Anthropic that lets AI models interact with external tools in a structured way. Think of it as a universal adapter between AI and software. Instead of just generating text, a model connected through MCP can request actions and receive structured results back.

The Playwright MCP server is the official implementation maintained by Microsoft. It runs locally, which keeps your browser automation private and secure. No data leaves your machine.

In practice, it sits between an AI client (like VS Code with GitHub Copilot, Cursor, Windsurf, or Claude Code) and your Playwright browser automation stack. The AI decides what needs to happen. The MCP server executes it in a real browser and returns page state. The AI reads the response and decides the next step.

I've been using Playwright MCP since its early releases, and the thing that surprised me most was how different it feels from traditional test generation. The AI isn't guessing. It's observing the actual page and reacting to what it sees. That feedback loop changes everything about how you write tests.

How it works: the client-server model

The MCP architecture has 2 sides:

• MCP client: the AI tool you interact with. This could be Cursor, VS Code with GitHub Copilot, Claude Code, Claude Desktop, or any MCP-compatible interface.
• MCP server: a local service (started via npx @playwright/mcp@latest) that receives requests from the client, executes browser actions using Playwright, and returns structured results.

The server extends what LLMs can do. Instead of generating code and hoping it works, the model can navigate pages, click elements, fill forms, capture screenshots, and read the page's accessibility tree, all through well-defined tool calls.

This creates a feedback loop. The AI acts, observes the result, and adapts. That's what makes Playwright MCP different from static code generation.

For teams already tracking Playwright market share trends, MCP is the feature that's accelerating adoption among AI-first engineering teams.

Why use Playwright MCP for automated testing?

Speed. That's the short answer.

The longer answer: most test automation effort goes into translating human intent into stable code. You write test cases in a document, then spend hours converting those steps into selectors, waits, and assertions that don't break every sprint.

Playwright MCP shortcuts this entire process. You describe what to test. The AI opens a real browser session, interacts with your app through the MCP server, and generates Playwright code from real page state, not guesswork.

The AI picks better locators because it reads the accessibility tree. It adds correct waits because it observes actual load behavior. It captures artifacts like traces and screenshots automatically.

Teams still review the generated tests. But they spend far less time scripting and more time deciding test coverage and CI priorities.

When NOT to use Playwright MCP: Full regression suites running on every CI commit. MCP is best for generating and validating new tests. For execution at scale, use standard Playwright sharding in your CI pipeline.

How Playwright MCP works

Snapshot mode vs vision mode

This is the part most guides skip, and it matters a lot.

Playwright MCP operates in 2 distinct modes that determine how the AI perceives the page:

Snapshot mode (default) is the core innovation. Instead of taking a screenshot and analyzing pixels, the server reads the browser's accessibility tree, the same semantic structure that screen readers use. Every element on the page gets a role, a name, a state, and a position in the hierarchy.

This is why Playwright MCP is more reliable than vision-based tools. The AI knows that a button labeled "Submit" is a button, regardless of its CSS styling, position on screen, or visual appearance. No pixel matching. No OCR. Just structured semantic data.

Vision mode is the fallback for edge cases. Some UI elements don't have good accessibility tree representations, think canvas-based apps, complex SVGs, or custom-drawn game UIs. Vision mode uses coordinate-based interaction, where the AI analyzes a screenshot and clicks at specific pixel positions.

You enable it by adding --caps=vision to your server configuration. But here's my honest take: for the vast majority of web apps, snapshot mode is faster, cheaper on tokens, and more reliable. I've only needed vision mode twice across dozens of projects, both times for canvas-based charting libraries.

Bottom line: start with snapshot mode (it's the default). Only switch to vision when the accessibility tree isn't giving you what you need.

Pro Tip: If your app has proper accessibility attributes, snapshot mode works even better. Good a11y = good MCP results.

Architecture and components

Playwright MCP architecture has a few focused components that work together to let AI safely drive a real browser.

1. MCP client

An AI-enabled tool like VS Code, Cursor, Windsurf, or Claude Desktop sends structured MCP requests. It decides what needs to happen but never executes browser actions itself.

2. Playwright MCP server

A local or remote service started via npx @playwright/mcp that exposes browser actions as MCP tools. It uses Playwright internally to execute navigation, interactions, waits, tracing, and assertions.

3. Browser and context

The server controls real browser instances and their state. It can reuse persistent profiles for realistic flows or run isolated sessions for clean, test-like execution.

4. Request-response loop

The client sends an action request, the server executes it, and structured page state comes back. Feedback is semantic, based on accessibility and DOM state, not screenshots.

5. Output and diagnostics

During execution, the server can capture traces, videos, logs, and session state to support debugging and replay.

6. Deployment modes

The same architecture runs locally via npx, as a standalone HTTP MCP server, inside Docker, or through the Playwright MCP Bridge Chrome extension. Only the transport changes.

Playwright MCP workflow example

Here's how a simple natural-language request flows through Playwright MCP, from AI intent to real browser execution and back:

1. User intent: You type: "Test the login button."
2. AI interpretation: The AI determines that it needs to open the login page and inspect the UI.
3. MCP request: The AI sends a structured MCP request to the Playwright server to navigate to /login.
4. Browser execution: The Playwright MCP server opens the page in a real browser and waits for it to load.
5. Structured response: The server returns page state and metadata, including URL, load status, and the page's accessibility tree snapshot.
6. Next action: The AI analyzes the response and decides the next step, for example, locating and clicking the login button, then verifying the result.

This loop continues until the task is complete. Each step is informed by real browser state, not predictions.

Playwright MCP vs Playwright CLI

This is the biggest ecosystem shift since MCP launched. If you're evaluating Playwright MCP in 2026, you need to understand this before choosing a setup.

In early 2026, Microsoft released @playwright/cli, a companion tool that takes a completely different approach to connecting AI agents with Playwright.

The key difference: token efficiency. A typical browser automation task consumes about 114,000 tokens through MCP. The same task through CLI uses about 27,000 tokens. That's roughly a 4x reduction.

Why the gap? MCP streams the full accessibility tree and screenshot data into the AI's context window at every step. CLI saves snapshots and screenshots to disk as YAML files, and the agent reads only what it needs. For coding agents like Claude Code or GitHub Copilot, this is a much more natural workflow, since they already operate through terminals and file systems.

Here's a comparison to help you decide:

Which should you use?

If you're using Cursor, Claude Desktop, or Windsurf, stick with MCP. These clients don't have filesystem access, so CLI won't work.

If you're using Claude Code, GitHub Copilot's Coding Agent, or Goose, try CLI first. The token savings are real and they compound across long sessions.

You can also use Cursor with both MCP and CLI depending on the task. MCP for exploratory testing, CLI for batch test generation.

For the full comparison with migration steps and token benchmarks, read our Playwright CLI vs MCP deep dive.

What's new in Playwright MCP (2026)

The Playwright MCP ecosystem evolved fast since the original release. If you learned MCP in 2025, things have changed. Here's what shipped, organized by what matters most for your workflow.

Playwright CLI companion (v0.0.56+)

The biggest addition. Microsoft's own README now says: "If you are using a coding agent, you might benefit from using the CLI+SKILLS instead." Agents learn CLI syntax from Playwright Skills (structured markdown guides) rather than loading MCP protocol schemas. Full details in the CLI deep dive.

Session management overhaul (v0.0.64+)

The old session-* commands are gone. Replaced with simpler alternatives:

• list to see all active sessions
• close-all to shut down browsers gracefully
• kill-all to force-terminate everything

Sessions are now binary: running or gone. No more confusing "stopped" state. Browser profiles are ephemeral by default (in-memory), starting clean with no leftover state. Use --persistent or --profile=<path> if you need cookies to survive between sessions.

Security hardening

Playwright MCP now ships with tighter defaults out of the box:

• File system access is restricted to the workspace root. Navigation to file:// URLs is blocked.
• Use --allow-unrestricted-file-access to opt out (think twice before using it).
• New origin controls: --allowed-origins and --blocked-origins let you whitelist or blacklist domains the browser can access.

For enterprise teams evaluating Playwright MCP for production CI workflows, these defaults make the security conversation much easier.

Docker support

An official Docker image is available at mcr.microsoft.com/playwright/mcp:

{
  "mcpServers": {
    "playwright": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "--init", "--pull=always", "mcr.microsoft.com/playwright/mcp"]
    }
  }
}

One limitation: Docker currently supports headless Chromium only. No Firefox or WebKit in containers yet. For cross-browser testing, use the local npx installation.

Chrome Extension: Playwright MCP Bridge (v0.0.67)

This Chrome extension connects MCP to pages in an existing browser session. It uses your default profile, meaning cookies, logged-in state, and localStorage are all intact.

Why this matters: testing authenticated flows without scripting a login sequence. Log in manually once in Chrome, then let the AI automate everything else through the bridge. This alone has saved me 20+ minutes per exploratory session on apps with complex auth flows.

Video recording and DevTools (v0.0.62+)

On-demand video recording is available via --save-video=800x600. Combined with --caps=devtools, you can capture performance traces, Core Web Vitals (LCP, CLS, INP), and full video playback. This pairs well with Playwright's built-in trace viewer for deep debugging.

GitHub Copilot integration

Playwright MCP is configured automatically for GitHub Copilot's Coding Agent. No setup needed. The agent can navigate, interact with, and screenshot web pages on localhost during code generation.

Incremental snapshots (v0.0.67+)

Snapshot mode now defaults to incremental. Instead of sending the full accessibility tree on every step, it sends only what changed. This cuts token usage and speeds up responses in long sessions.

Want the full AI ecosystem picture? MCP is just 1 layer. The Playwright AI ecosystem guide covers the complete stack: MCP, CLI, built-in agents (Planner, Generator, Healer), and third-party platforms.

Benefits and limitations of Playwright MCP

You should know both sides before committing to MCP in your test automation workflow.

How to set up Playwright MCP

Before setting up, make sure your system meets a few basic requirements so installation and connection work smoothly. Once configured, the Playwright MCP server acts as the execution layer between AI clients and your Playwright browser automation stack.

If you're brand new to Playwright, set up the framework first, then come back here for MCP.

Prerequisites

• Node.js 18 or newer installed and available on your command line.
• npm or a compatible package manager, since the server runs through npx with no global install required.
• An MCP-compatible client such as VS Code with GitHub Copilot, Cursor, Windsurf, Claude Code, or Claude Desktop.

Install Playwright browsers (recommended)

Install browser binaries once so Playwright can run reliably:

npx playwright install

Common MCP configuration

Many popular editors, including Cursor and Windsurf, are built on the VS Code codebase and follow the same configuration approach. The setup relies on a common JSON configuration file (mcp.json) that works consistently across these environments.

You don't need to install the Playwright MCP package globally. Your IDE runs the server through npx.

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

1. VS Code setup

VS Code natively supports MCP server configurations.

This setup follows the MCP configuration flow used by VS Code-based editors to connect external execution servers.

1. Open Visual Studio Code and make sure GitHub Copilot is enabled.
2. Place the common MCP configuration file at <project root>/.vscode/mcp.json in your project.
3. Save this JSON file.
4. Restart VS Code to apply the MCP configuration.
5. Verify the setup by asking Copilot to perform a real browser action, such as opening a page or capturing a screenshot.

You can also use the command line shortcut:

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

Once configured, VS Code connects to Playwright MCP. AI tools inside the editor can run tests, inspect results, and debug directly from your workspace.

2. Cursor setup

Cursor lets you register MCP servers directly from its settings, making Playwright MCP part of the editor workflow.

Cursor follows the same MCP registration pattern, with editor-specific UI differences handled at the settings level.

1. Open Cursor Settings.
2. Navigate to the Tools & MCP tab and click the Add Custom MCP button.
3. Place the common MCP configuration file at <project root>/.cursor/mcp.json in your project.
4. Save the JSON file and restart the Cursor IDE.
5. Verify the Playwright MCP integration by returning to Tools & MCP and confirming it appears as configured.

For the full Cursor + MCP + TestDino workflow (including using Playwright Skills and the Playwright Healer agent), see our dedicated Cursor with Playwright guide.

3. Windsurf setup

Windsurf installs Playwright MCP through its built-in marketplace, which abstracts away most of the manual MCP configuration steps.

1. Open Windsurf Settings using Ctrl + , or Cmd + ,
2. Switch to the Cascade tab.
3. Open the MCP Marketplace and search for Playwright MCP.
4. Click Install to add the MCP integration.
5. Confirm that Playwright MCP appears as active in the Marketplace.

If you're using an IDE not listed above, the setup follows a similar pattern. We've documented JetBrains, Zed, and Goose configurations separately.

Set up Playwright MCP on other IDEs

4. Claude Code setup

Claude Code is Anthropic's developer-focused CLI that lets you run Claude in your terminal and connect it to local tools through MCP.

Claude Code connects to Playwright MCP through explicit command registration, as defined by the MCP server specification.

1. Install Claude Code and ensure you're authenticated. (Requires an active Claude subscription or Anthropic Console credits.)
2. Launch Claude Code from the terminal by entering: claude
3. Add and connect Playwright MCP:
   
   terminal

   claude mcp add playwright npx @playwright/mcp@latest
   
4. Check that the integration is successful by running: /mcp
5. You should see Playwright listed as an active local MCP server.

5. Claude Desktop setup

Claude Desktop offers native MCP support and is popular for non-coding workflows like exploratory testing and bug reproduction.

1. Locate the Claude Desktop config file:
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\\Claude\\claude_desktop_config.json
2. Add the Playwright MCP server configuration:

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

Restart Claude Desktop completely. Close it and terminate any running processes from Task Manager or Activity Monitor.

Start a new conversation and try: "Use Playwright to navigate to http://example.com and tell me the page title."

Claude Desktop launches a visible browser window by default. You'll see the browser open and the AI controlling it in real time. This makes it great for demos and understanding how MCP works before using it in a coding environment.

6. Docker setup

For teams that need isolated, reproducible environments, especially in CI or shared development setups:

{
  "mcpServers": {
    "playwright": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "--init", "--pull=always", "mcr.microsoft.com/playwright/mcp"]
    }
  }
}

Docker supports headless Chromium only at this time. For cross-browser testing with Firefox and WebKit, use the local npx installation.

Alternative installation methods

If you prefer automated installation:

Using Smithery:

npx @smithery/cli install @playwright/mcp --client claude

Using MCP-Get:

npx @michaellatman/mcp-get@latest install @playwright/mcp

Both tools handle configuration file updates automatically.

Best practices for Playwright MCP

Using Playwright MCP well requires a slightly different mindset than traditional Playwright automation.

Be specific in your prompts. Don't say "test the login page." Instead, try something like this:

Use it as an exploration tool first. Let the AI navigate real pages and observe UI state before generating tests. This builds better context than jumping straight to code generation.

Ask for a test plan before code. Have the AI create a clear plan covering navigation, assertions, and setup steps. Then generate the code. This keeps tests well structured.

Enforce Playwright locator best practices in prompts. Prefer getByRole, getByTestId, and accessible labels over CSS or XPath selectors. These are more stable and match how Playwright MCP reads the page.

Keep generated tests small and single-purpose. 1 test, 1 behavior. This improves stability and makes debugging simpler.

Require the AI to run and re-run tests. Don't accept generated code until it passes consistently. MCP lets the AI execute tests directly, so use that ability.

Treat traces and screenshots as first-class artifacts. Use them to understand failures instead of guessing from error messages. The Playwright Trace Viewer is your best friend here.

Use Playwright MCP for creation, CI for execution. Keep large regression suites in standard Playwright CI pipelines. Use MCP for new features, bug reproduction, and test validation.

Watch your token budget. For long sessions or complex pages, consider switching to Playwright CLI for 4x token savings.

These practices reflect Playwright's own guidance and how engineers like Debbie O'Brien use MCP to explore flows and validate selectors in real browser sessions.

Troubleshooting Playwright MCP issues

Even with a correct setup, execution issues happen. Here are the most common problems with specific fixes.

If your issue isn't listed here, check the Playwright MCP GitHub Issues page for known bugs and community workarounds.

Conclusion

Playwright MCP removes the friction of manual script writing and constant context switching. It speeds up how tests are created and iterated by letting AI work with a real browser instead of predicting behavior from code alone.

Once you've used AI-driven test generation, the next challenge is scaling and maintaining those tests with confidence. The tests MCP generates still need to run in CI, still produce reports, and still fail in ways that need fast diagnosis.

That's where a test reporting tool like TestDino fits in. It takes the Playwright results from your CI runs and gives you AI-powered failure analysis, flaky test detection, and error grouping, so your team knows exactly what broke and why. You can even connect TestDino's MCP server to your IDE alongside Playwright MCP, so AI agents can query your test history and failure patterns while generating new tests.

After setting up Playwright MCP, pair it with TestDino to analyze failures and stabilize flaky Playwright tests from a single reporting dashboard.

Fix your flaky tests instantly

Turn unreliable Playwright tests into stable, trusted checks.

Try TestDino free Try TestDino free

FAQs