MCP • PLAYWRIGHT • AI TESTING • PRACTICAL TUTORIAL

Playwright
MCP Tutorial
2026

Connect an AI assistant to a real browser and let it navigate, click, type, inspect, test and investigate web applications using Playwright and the Model Context Protocol.

Playwright MCP Model Context Protocol Browser Automation AI Agents Software Testing
AI Assistant Claude / VS Code / Cursor / other MCP client
↓
Playwright MCP Server Browser tools + structured accessibility snapshots
↓
Real Browser Chrome • Firefox • WebKit • Edge
↓
Your Application Navigate • Inspect • Interact • Verify
MCP AI ↔ tools protocol
Browser Real interaction
Snapshot Structured page state
Agent Reason + act
Start here

What exactly is Playwright MCP?

Playwright MCP is a Model Context Protocol server that exposes browser automation capabilities to AI assistants.

Instead of an AI assistant merely telling you how to interact with a web application, it can use Playwright MCP to actually open a browser, navigate to the application, inspect the page and interact with it.

The big idea: your AI assistant becomes capable of operating a browser using Playwright tools rather than simply producing text instructions.

Playwright MCP primarily works from structured accessibility snapshots. These describe elements such as headings, textboxes, buttons, checkboxes and links together with references that the AI can use for subsequent actions.

Architecture

How MCP connects AI to the browser

AI

AI Client

You describe what you want in natural language.

→
MCP

Playwright MCP

Exposes browser capabilities as tools that the AI can call.

→
WEB

Browser

Playwright performs the real browser actions against the application.

Think of MCP as the bridge. The language model provides reasoning and intent. Playwright provides reliable browser automation. MCP gives the model a structured way to use those capabilities.
Why this matters

Normal AI assistant vs AI with Playwright MCP

Without browser tools

  • AI explains what you should click
  • AI writes sample automation code
  • You execute the instructions
  • AI cannot see current application state
  • Debugging depends on what you provide

With Playwright MCP

  • AI can navigate the application
  • AI reads the current page structure
  • AI can click and type
  • AI can inspect updated state
  • AI can perform multi-step browser tasks
Core concept

Accessibility snapshots: how the AI “sees” the page

Playwright MCP does not need to rely solely on screenshots or guessed screen coordinates. It can receive structured information describing accessible page elements.

heading "todos" [level=1]

textbox "What needs to be done?" [ref=e5]

listitem
  ↳ checkbox "Toggle Todo" [ref=e10]
  ↳ text: Buy groceries

The model can identify that e5 is the textbox and then pass that reference to the next browser action.

Conceptual MCP action Type into element 
browser_type {
    target: "e5",
    text: "Run regression tests"
}
Hands-on setup

Step 1 — Check the prerequisites

At the time of writing, Playwright's official MCP documentation requires Node.js 20 or newer plus an MCP-compatible client.

  • Node.js 20+
  • VS Code, Cursor, Windsurf, Claude Code, Claude Desktop or another MCP client
  • An application or website to interact with

Step 2 — Add the Playwright MCP server

The standard MCP configuration is:

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

Your MCP client determines where this configuration should be placed. Some clients also provide a UI for installing MCP servers.

Popular clients

Example client setup

VS

VS Code

Playwright's documentation provides a command-line MCP installation option for VS Code.

CC

Claude Code

The MCP server can be registered directly using Claude Code's MCP configuration command.

CU

Cursor

Cursor lets you add an MCP server from its MCP settings using the Playwright npx command.

Claude Code example

Terminal Claude Code 
claude mcp add playwright npx @playwright/mcp@latest

VS Code CLI example

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

Step 3 — Let the AI operate a real browser

Once MCP is connected, give your assistant a concrete browser task.

Example prompt

Navigate to https://demo.playwright.dev/todomvc, add “Run smoke tests”, add “Review defect report”, complete the first task and tell me how many active tasks remain.

Behind the scenes, the interaction follows a repeated loop.

1

Navigate

Playwright opens the requested application in a browser.

2

Receive a snapshot

The MCP server returns a structured representation of the current page state.

3

Reason

The AI identifies the relevant textbox, checkbox, button or link.

4

Interact

The AI calls the corresponding Playwright MCP tool using the relevant element reference.

5

Observe the new state

The next snapshot shows the changed application state, allowing the agent to continue.

Visualise it

The MCP browser interaction loop

PLAYWRIGHT MCP 1. USER INTENT Natural language request 2. SNAPSHOT Page roles + references 3. AI DECIDES Select next action 4. BROWSER ACTS Click • type • navigate
For testers

What can QA engineers actually use it for?

🧭

Exploratory testing

Ask the agent to explore a workflow, identify unusual states or walk through critical user journeys.

📝

Form testing

Populate fields, select options, submit data and inspect resulting behaviour.

🔗

Navigation testing

Follow links, verify navigation flows and check whether important user paths remain reachable.

📸

Evidence capture

Capture screenshots where useful while retaining structured state for reasoning.

🌐

Network investigation

Inspect requests and investigate client-server behaviour during browser workflows.

🧪

API mocking

Mock selected network responses to investigate UI behaviour under controlled backend conditions.

🔐

Authenticated journeys

Persist or restore browser state so authenticated workflows can be reused across sessions where appropriate.

🐞

Debugging

Combine browser state, console information and network activity to investigate failures.

Practical skill

Better prompts produce better testing

The agent still needs a useful testing objective. “Test this website” is usually a weak instruction.

Weak prompt

Test the checkout page.

Better prompt

Explore the checkout flow from basket to confirmation. Focus on required-field validation, quantity changes, invalid discount codes and preserving the basket after validation errors. Do not submit a real order. Summarise any unexpected behaviour with reproduction steps.

Testing lesson: AI agents become more useful when the tester provides scope, constraints, risks and expected outcomes.
Configuration

Headed vs headless browser

Playwright MCP currently opens the browser in headed mode by default, which is particularly useful while learning because you can watch the agent perform actions.

For headless execution, add the headless argument:

MCP config Headless 
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--headless"
      ]
    }
  }
}

Choose another browser

You can also specify a browser.

Example Firefox 
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--browser=firefox"
      ]
    }
  }
}

Current documented browser options include Chrome, Firefox, WebKit and Microsoft Edge.

Useful feature

Persistent vs isolated sessions

Persistent profile

  • Default mode
  • Cookies can survive between sessions
  • Login state can persist
  • Useful for repeated workflows

Isolated profile

  • Start with a clean session
  • Useful for repeatable testing
  • Avoid hidden state influencing results
  • Can load predefined storage state
Testing recommendation: for deterministic automation, understand exactly which browser state is being reused. Persistent sessions are convenient, but hidden state can change test behaviour.
Important distinction

Playwright MCP is not the same as a regression test suite

Use case Playwright MCP Playwright Test
Interactive AI exploration Excellent fit Not its primary purpose
Natural-language browser task Excellent fit Requires test/code creation
Repeatable CI regression suite Possible supporting role Excellent fit
Version-controlled test cases Not the main model Excellent fit
Exploratory investigation Excellent fit More scripted
Deterministic release gate Use carefully Preferred approach
Best pattern: use MCP to explore, investigate and accelerate. Turn stable, valuable scenarios into conventional Playwright tests when you need dependable regression coverage.
Security

Be careful when giving an AI browser access

An MCP-enabled agent can perform real browser actions, so the same care you apply to automation credentials and test environments should apply here.

Do not casually give an agent unrestricted access to sensitive production accounts.

Use dedicated test users, restricted permissions and controlled environments whenever possible.

  • Prefer test environments where possible
  • Use least-privilege accounts
  • Do not expose secrets unnecessarily
  • Be cautious with destructive actions
  • Review prompts before allowing purchases or data deletion
  • Understand which browser profile and credentials are active

A particularly important advanced option

Playwright documents an unsafe code-execution capability for running arbitrary Playwright JavaScript in the MCP server process. Because this is effectively equivalent to remote code execution, it should only be enabled for trusted clients and trusted workflows.

SoftwareTestingPortal workflow

A practical 6-step MCP testing approach

1

Define the mission

Specify the workflow, business risk and boundaries of the exploration.

2

Use controlled data

Choose safe test accounts and avoid accidental production changes.

3

Let the agent explore

Allow MCP to navigate, inspect and interact while you observe the reasoning outcome.

4

Challenge the happy path

Explicitly ask for negative, boundary and state-transition scenarios.

5

Review evidence

Check page state, screenshots, network behaviour and reported findings.

6

Convert valuable findings into tests

Where repeatability matters, turn proven scenarios into maintainable Playwright regression tests.

FAQ

Frequently asked questions

What does MCP stand for?
MCP stands for Model Context Protocol. It provides a standard way for AI applications to connect to tools and external capabilities.
Does Playwright MCP require screenshots?
No. Its core interaction model uses structured accessibility snapshots, although screenshot capabilities are also available when visual evidence is useful.
Can Playwright MCP click and type on websites?
Yes. It exposes browser capabilities including navigation, clicking, typing, form interaction, keyboard actions and more.
Can it work with Firefox or WebKit?
Yes. Current Playwright MCP configuration supports Chrome, Firefox, WebKit and Microsoft Edge.
Is Playwright MCP a replacement for Playwright Test?
No. MCP is especially useful for interactive and agentic browser workflows. Playwright Test remains highly appropriate for repeatable, version-controlled regression automation and CI.
Can I use authenticated browser sessions?
Yes. Playwright MCP supports persistent browser profiles as well as isolated sessions and saved storage state.
Should testers learn MCP?
Testers do not need to become protocol engineers, but understanding how AI agents connect to browser tools is becoming increasingly useful for modern QA, agent testing and AI-assisted automation.
Continue learning

You have now connected AI reasoning to a real browser.

Playwright MCP demonstrates a major shift in automation: instead of only generating test code, AI systems can inspect current application state, choose browser actions and perform interactive workflows.

The next step is even more important for QA professionals: learning how to test AI agents themselves.

NEXT: HOW TO TEST AI AGENTS →
Scroll to Top