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

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 MCP client, 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.

What is Playwright MCP?

The Playwright MCP server is a Model Context Protocol (MCP) server built by Microsoft that gives AI models direct browser automation capabilities using the Playwright framework. Instead of relying on screenshots or pixel-based interactions, it provides LLMs with a structured accessibility snapshot of web pages, allowing AI to interact with elements deterministically using unique references.

In simpler terms: Playwright MCP is a bridge between your AI assistant (Claude, Copilot, Cursor, Grok, or any MCP-compatible client) and a real browser. The AI sends commands like "click the Sign In button" or "type [email protected] into the email field," and Playwright MCP executes them in an actual browser session.

The server uses Playwright's accessibility tree instead of screenshots. This means:

• No vision models needed. The AI works with structured text data, not images.

• Deterministic element targeting. Each element gets a unique ref (e.g., ref="e5"), eliminating the ambiguity of coordinate-based clicking.

• Faster and cheaper. Text-based accessibility snapshots consume fewer tokens than base64-encoded screenshots.

Playwright MCP was originally released by Microsoft in late 2025 and has grown to over 36,000 GitHub stars. It works with any MCP-compliant client and supports Chromium, Firefox, and WebKit browsers.

How does Playwright MCP differ from regular Playwright?

Regular Playwright is a testing framework where you write scripts in TypeScript, Python, Java, or C# to automate browsers. You control every action programmatically.

Playwright MCP wraps Playwright's capabilities behind the Model Context Protocol, so an AI model can control the browser conversationally. Instead of writing await page.click('#submit'), you tell the AI "click the submit button" and MCP handles the translation.

The key difference: regular Playwright is code-first. Playwright MCP is AI-first.

Why use Playwright MCP for automated testing?

Using Playwright MCP for test automation addresses real problems that teams face every day:

Faster test creation. Writing end-to-end tests from scratch takes hours. With MCP, you describe the user flow in plain English, and the AI generates working Playwright test code by interacting with the real application.

Better selectors from the start. Because MCP reads the accessibility tree, the AI naturally uses semantic selectors like getByRole and getByTestId instead of brittle CSS selectors or XPath.

Live debugging with context. When a test fails, you can ask the AI to navigate to the failing page, inspect the current state, and suggest fixes - all within the same browser session.

Exploratory testing at scale. QA engineers can direct the AI to explore user flows, reproduce bugs, and validate edge cases without writing a single line of code.

Lower barrier to entry. Team members who aren't comfortable writing Playwright scripts can still create and validate tests using natural language.

Here's what MCP doesn't replace: stable, human-reviewed regression suites that run in CI. MCP is best for creation and exploration. CI pipelines should run standard Playwright test scripts.

How Playwright MCP works

Playwright MCP operates through a structured loop between the AI model and the browser:

Step 1: Snapshot. The AI requests a browser_snapshot from MCP. The server captures the page's accessibility tree and returns it as structured text with element references.

Step 2: Decision. The AI reads the snapshot, identifies the target element by its ref attribute (e.g., ref="e12" for a login button), and decides what action to take.

Step 3: Action. The AI calls an MCP tool like browser_click(ref="e12") or browser_type(ref="e7", text="[email protected]"). MCP executes the action in the real browser.

Step 4: Updated snapshot. After the action, MCP returns a new accessibility snapshot reflecting the updated page state. The AI uses this to decide its next step.

This loop continues until the task is complete. The AI never "guesses" what's on the page - it always works from the latest accessibility data.

Snapshot mode vs. Vision mode

Playwright MCP supports two primary operating modes:

Snapshot mode (default). Uses the accessibility tree. Fast, deterministic, and token-efficient. This is the recommended mode for most use cases.

Vision mode. Uses screenshots instead of accessibility snapshots. Enables coordinate-based interactions (clicking at specific x,y positions). Useful for canvas elements, games, or pages with poor accessibility markup. Enable it with --caps=vision.

Most teams should stick with snapshot mode. Vision mode is primarily for edge cases where the accessibility tree doesn't capture the relevant UI elements.

Playwright MCP tools reference

Playwright MCP exposes a comprehensive set of tools that the AI agent can use to interact with the browser. Understanding what's available helps you write better prompts and debug issues faster.

Core tools (always enabled)

Extended capability groups

Enable additional tools using the --caps flag or the capabilities config option:

To enable all capabilities:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest", "--caps=core,network,storage,vision"]
    }
  }
}

To disable capabilities entirely (reduces token usage):

npx @playwright/mcp@latest --caps=none

Playwright MCP vs Playwright CLI

Microsoft now offers two distinct interfaces for AI-browser interaction. Choosing the right one depends on your workflow.

When to use MCP

• You're working in an IDE with MCP support (Cursor, VS Code, Windsurf)

• You want the AI to interactively explore pages and reason about what it sees

• You need exploratory testing, bug reproduction, or live debugging

• You're building self-healing tests or long-running autonomous workflows

When to use CLI

• You're using a terminal-based coding agent (Claude Code, Copilot CLI, Codex)

• Token budget matters (CLI uses 4x fewer tokens)

• You're generating tests in batch or running automated pipelines

• You need to balance browser automation with large codebase reasoning

What's new in Playwright MCP and the Playwright agentic stack (2026)

The Playwright team shipped major updates in 2026 that reshaped how AI agents interact with browsers. Here's what changed and why it matters.

Playwright 1.59: Screencast API

Screencast lets agents record a video of their work with chapter markers, action annotations, and visual overlays. Instead of reading text logs to verify what an agent did, reviewers can watch a timestamped video.

Why it matters for testing: autonomous test generation is only useful if humans can verify what happened. Screencast provides the "receipt" that makes AI-generated tests trustworthy.

Playwright 1.59: browser.bind()

browser.bind() lets a single browser instance be shared across the Playwright MCP server, the CLI, and any custom Playwright client simultaneously. Instead of each tool launching its own browser, they all connect to one bound session.

This enables mixed human/agent workflows: a QA engineer logs in manually (handling MFA, CAPTCHA), then hands off control to an AI agent in the same authenticated browser session.

Playwright CLI + SKILLS

Microsoft introduced the Playwright CLI as a lighter alternative to MCP for coding agents. CLI uses shell commands instead of the MCP protocol, avoiding the overhead of loading large tool schemas into the model's context window.

SKILLS are markdown instruction files that teach agents how to use CLI tools effectively. They're the equivalent of system prompts but designed for CLI-based workflows.

Test Agents: Planner, Generator, Healer

Playwright 1.59 introduced three specialized test agents that can be invoked from Claude Code:

• Planner. Analyzes the application and creates a structured test plan covering navigation, user flows, and edge cases.

• Generator. Takes a plan and generates working Playwright test code by interacting with the real application through MCP.

• Healer. Monitors failing tests and automatically attempts to fix broken selectors or adapt to UI changes.

Initialize them in Claude Code with:

npx playwright init-agents --loop=claude

Benefits and limitations of Playwright MCP

Benefits

• No vision models required. Works purely on structured accessibility data.

• Cross-browser support. Chromium, Firefox, and WebKit.

• Device emulation. Test on mobile viewports with --device="iPhone 15".

• Network interception. Mock API responses for isolated testing.

• Persistent sessions. Maintain login state across interactions.

• Works with any MCP client. Not locked to a specific AI provider.

• Open source. Apache-2.0 license, actively maintained by Microsoft.

Limitations

• Token-intensive for complex pages. Large accessibility trees can fill context windows.

• Not a replacement for CI suites. Generated tests need human review before committing to regression.

• Accessibility tree gaps. Canvas elements, SVGs, and custom widgets may not be fully represented.

• Single browser per profile. Persistent profiles can't be shared across concurrent MCP sessions.

• AI hallucinations. The model may attempt actions on elements that don't exist or misinterpret the page structure.

How to set up Playwright MCP

Prerequisites

Before setting up Playwright MCP, ensure you have:

• Node.js 18 or newer (Node.js 20+ recommended)

• An MCP-compatible client - VS Code, Cursor, Windsurf, Claude Desktop, Claude Code, Copilot, Grok, Codex, or any other MCP client

• Internet connection for the initial package download

Standard configuration

The core configuration works across most MCP clients:

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

Add this to your client's MCP configuration file, then restart the client. Below are step-by-step instructions for each supported IDE and tool.

1. VS Code setup (GitHub Copilot)

VS Code has native MCP support through GitHub Copilot. Two ways to add it:

Option A: VS Code CLI

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

Option B: Manual configuration

1. Open Settings → search for MCP

2. Click Edit in settings.json

3. Add the standard Playwright MCP configuration

4. Restart VS Code

After installation, the Playwright MCP server will be available in GitHub Copilot's agent chat.

2. Cursor setup

1. Open Cursor Settings → MCP → Add new MCP Server

2. Name it playwright

3. Select command type

4. Enter the command: npx @playwright/mcp@latest

5. Click Save

You can also click Edit to add advanced arguments like --headless or --browser=firefox.

3. Windsurf setup

Follow the Windsurf MCP documentation. Use the standard configuration block above.

4. Claude Code setup

Claude Code uses a CLI command for MCP server registration:

claude mcp add playwright npx @playwright/mcp@latest

Verify the integration by running: /mcp

You should see Playwright listed as an active local MCP server.

For the Test Agents experience in Claude Code specifically, also run:

npx playwright init-agents --loop=claude

This adds the Planner, Generator, and Healer agent definitions as Claude Code subagents you can invoke by name.

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

1. Add the Playwright MCP server configuration:

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

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

2. 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. GitHub Copilot CLI setup

Use the Copilot CLI to interactively add the Playwright MCP server:

/mcp add

Or edit the config file ~/.copilot/mcp-config.json:

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

7. OpenAI Codex setup

codex mcp add playwright npx "@playwright/mcp@latest"

Or edit ~/.codex/config.toml:

[mcp_servers.playwright]
command = "npx"
args = ["@playwright/mcp@latest"]

8. Grok setup

grok mcp add playwright -- npx @playwright/mcp@latest

Or edit ~/.grok/config.toml:

[mcp_servers.playwright]
command = "npx"
args = ["@playwright/mcp@latest"]

9. Amp setup

Add via the Amp VS Code extension settings or update settings.json:

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

Or via Amp CLI:

amp mcp add playwright -- npx @playwright/mcp@latest

10. Cline setup

Add to cline_mcp_settings.json:

{
  "mcpServers": {
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "timeout": 30,
      "args": ["-y", "@playwright/mcp@latest"],
      "disabled": false
    }
  }
}

11. JetBrains Junie setup

1. Type /mcp in Junie

2. Press Ctrl+A to add a new MCP server

3. Select Playwright from the list

Or add to .junie/mcp/mcp.json:

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

12. Gemini CLI setup

Follow the Gemini CLI MCP server documentation. Use the standard config above.

13. Goose setup

Go to Advanced settings → Extensions → Add custom extension. Set type to STDIO and command to npx @playwright/mcp.

14. 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"]
    }
  }
}

For a long-lived container service:

docker run -d -i --rm --init --pull=always \
  --entrypoint node \
  --name playwright \
  -p 8931:8931 \
  mcr.microsoft.com/playwright/mcp \
  /app/cli.js --headless --browser chromium --no-sandbox --port 8931 --host 0.0.0.0

Then configure your MCP client to connect via HTTP:

{
  "mcpServers": {
    "playwright": {
      "url": "http://localhost:8931/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.

Playwright MCP configuration options

Playwright MCP supports extensive configuration through command-line flags, environment variables, or a JSON config file. Here's a reference of the most important options.

Commonly used flags

Using a configuration file

For complex setups, use a JSON config file instead of CLI flags:

npx @playwright/mcp@latest --config path/to/config.json

Example configuration file:

{
  "browser": {
    "browserName": "chromium",
    "headless": false,
    "launchOptions": {
      "channel": "chrome"
    },
    "contextOptions": {
      "viewport": { "width": 1280, "height": 720 }
    }
  },
  "capabilities": ["core", "network"],
  "network": {
    "allowedOrigins": ["https://myapp.com:*"],
    "blockedOrigins": ["https://analytics.example.com:*"]
  },
  "outputDir": "./mcp-output",
  "codegen": "typescript"
}

User profile management

Playwright MCP can run in three profile modes:

Persistent profile (default). All login sessions, cookies, and browser data are saved between sessions. Profile location:

• Windows: %USERPROFILE%\AppData\Local\ms-playwright\mcp-{channel}-{workspace-hash}

• macOS: ~/Library/Caches/ms-playwright/mcp-{channel}-{workspace-hash}

• Linux: ~/.cache/ms-playwright/mcp-{channel}-{workspace-hash}

The {workspace-hash} is derived from the MCP client's workspace root, so different projects get separate profiles automatically.

Isolated mode. Each session starts fresh. When the browser closes, all session data is lost. Ideal for testing scenarios that need clean state:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest", "--isolated", "--storage-state=auth.json"]
    }
  }
}

Browser Extension mode. The Playwright MCP Chrome Extension lets you connect to existing browser tabs. This leverages your already logged-in sessions and browser state - useful for testing behind corporate SSO or complex auth flows.

Programmatic usage

You can also use Playwright MCP programmatically in your own Node.js applications:

import http from 'http';
import { createConnection } from '@playwright/mcp';
import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';

http.createServer(async (req, res) => {
  const connection = await createConnection({
    browser: { launchOptions: { headless: true } }
  });
  const transport = new SSEServerTransport('/messages', res);
  await connection.connect(transport);
});

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:

More detail leads to more consistent, deterministic results.

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.

FAQs

Can Playwright MCP fully replace writing Playwright test code?

No. Playwright MCP helps reduce manual effort during test exploration, debugging, and early test creation. Long-term regression suites still need human-reviewed Playwright code to remain stable and predictable.

What types of applications benefit most from Playwright MCP?

Applications under active development benefit the most. Products with frequent UI changes, new user flows, or complex interactions are ideal. Static or rarely updated applications see less value from MCP.

Is Playwright MCP tied to a specific AI provider?

No. MCP is an open protocol. While it was introduced by Anthropic, Playwright MCP works with any MCP-compatible client, including Claude, GitHub Copilot, Cursor, Grok, Codex, and more.

What's the difference between Playwright MCP and Playwright CLI?

MCP uses the Model Context Protocol to stream data between AI and browser. CLI uses shell commands and saves output to disk. MCP works with chat-based agents (Claude Desktop, Cursor). CLI works better with coding agents (Claude Code, Copilot) and uses 4x fewer tokens. See our full CLI vs MCP comparison above.

What is the Screencast API and why does it matter for agentic testing?

Screencast (introduced in Playwright 1.59) lets agents record a video of their work with chapter markers, action annotations, and visual overlays. This acts as a "receipt" that a human reviewer can watch instead of parsing text logs. For autonomous test authoring, it's the fastest way to build trust in what the agent did.

What does browser.bind() do in Playwright 1.59?

browser.bind() lets a single launched browser be shared across the Playwright MCP server, the CLI, and any custom Playwright client. Instead of each tool launching its own browser, they all connect to one bound session. This enables mixed human/agent workflows where a person logs in manually and then hands off control to an agent in the same browser.

How many tokens does Playwright MCP use per session?

Token usage depends on page complexity. Simple pages with a small accessibility tree may use 2,000–5,000 tokens per snapshot. Complex single-page applications can generate snapshots exceeding 20,000 tokens. For token-sensitive workflows, use --caps=none to reduce tool schema overhead, or switch to the Playwright CLI for up to 4x savings.

Can I use Playwright MCP in CI/CD pipelines?

Yes, but with caveats. Playwright MCP is designed for interactive AI-driven workflows, not high-volume regression testing. For CI/CD, use standard Playwright test runner (npx playwright test). Use MCP in CI only for specific tasks like AI-assisted test generation or debug triage, running it in Docker with --headless and --no-sandbox flags.