Playwright MCP: let an AI assistant explore your app, then write the test

Playwright MCP is Microsoft's official MCP server for Playwright. It gives an AI assistant such as Claude Code, GitHub Copilot or Cursor the tools to drive a real browser: navigate, click, fill forms and read the page. The assistant reads the page through structured accessibility snapshots, not screenshots, so no vision model is needed and it naturally "sees" the roles and accessible names that good Playwright locators are built on. This guide covers installation, a first explore-then-generate scenario, how MCP compares with Playwright CLI and the Playwright Test Agents, and the rules we teach to keep AI-generated tests trustworthy.

What is MCP (Model Context Protocol)?

The Model Context Protocol is an open protocol that standardises how an AI assistant connects to external tools. An "MCP server" exposes a list of tools, each described by a name, a description and parameters; the "client" (Claude Code, the GitHub Copilot agent in VS Code, Cursor…) presents them to the model, which decides which one to call and with which arguments. Each result comes back into the conversation and the model chains the next step.

Without MCP, a coding assistant can still write a Playwright test, but it writes it blind: it guesses button labels, form structure and page flow. With a browser MCP server, it can open the application, see what is actually displayed, and write the test from what it observed.

What is Playwright MCP?

Playwright MCP is the MCP server maintained by Microsoft's Playwright team. It launches a browser with Playwright and exposes tools such as browser_navigate (open a URL), browser_snapshot (read the page), browser_click, browser_type, browser_fill_form, browser_wait_for, browser_take_screenshot, browser_tabs, browser_evaluate, plus browser_console_messages and browser_network_requests to inspect the console and network calls.

Its key tool is browser_snapshot: instead of sending an image of the screen, it returns a structured accessibility snapshot, the tree of elements with their role (button, link, text box, heading), accessible name and state. The model sees the page the way assistive technologies do, which is exactly the point of view Playwright recommends for robust locators.

How do you install Playwright MCP?

Node.js is the only prerequisite, since the server runs with npx. The browser is headed by default, which is handy to watch what the assistant does.

Claude Code

claude mcp add playwright npx @playwright/mcp@latest

The server is then available in your Claude Code sessions: just ask it to open a page or test a user journey.

VS Code (GitHub Copilot agent mode)

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

The browser_* tools then appear in the Copilot agent's tool list.

Cursor and other MCP clients

Most clients accept the same standard JSON configuration in their MCP settings:

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

Options worth knowing

Append them after @playwright/mcp@latest in the command or in the args array:

A first scenario: explore a login page, then generate a test

Take a demo application running locally. The goal is twofold: let the assistant explore the login flow, then have it write a TypeScript Playwright test from what it actually observed.

Step 1: exploration

A precise prompt works far better than a vague one. For example:

Using Playwright MCP, open http://localhost:3000/login.
Describe the fields, buttons and messages on the page.
Then try to log in with a wrong password and report the exact error message.
Do not submit any other form.

The assistant calls browser_navigate, then browser_snapshot to read the page, fills the fields with browser_type or browser_fill_form, clicks with browser_click and reads the page again. You get a report of the elements (with their roles and accessible labels) and of the observed behaviour: a small, documented exploratory testing session.

Step 2: test generation

From what you observed, write tests/login.spec.ts with Playwright Test in TypeScript:
one successful login and one wrong-password case. Use getByRole and getByLabel only,
no CSS selectors, read credentials from environment variables.
Then run the tests and fix them if they fail.

A typical result looks like this (the base URL is set in playwright.config.ts):

import { test, expect } from '@playwright/test';

test.describe('Login', () => {
  test.beforeEach(async ({ page }) => {
    await page.goto('/login');
  });

  test('a valid user reaches the dashboard', async ({ page }) => {
    await page.getByLabel('Email').fill(process.env.TEST_USER_EMAIL!);
    await page.getByLabel('Password').fill(process.env.TEST_USER_PASSWORD!);
    await page.getByRole('button', { name: 'Sign in' }).click();

    await expect(page).toHaveURL(/\/dashboard/);
    await expect(page.getByRole('heading', { name: 'Dashboard' })).toBeVisible();
  });

  test('a wrong password shows an error', async ({ page }) => {
    await page.getByLabel('Email').fill(process.env.TEST_USER_EMAIL!);
    await page.getByLabel('Password').fill('wrong-password');
    await page.getByRole('button', { name: 'Sign in' }).click();

    await expect(page.getByRole('alert')).toContainText('Invalid credentials');
    await expect(page).toHaveURL(/\/login/);
  });
});

The labels ("Email", "Sign in", "Invalid credentials") come from the demo application; in your project they will come from the real exploration. That is the whole point: the test is written from the observed page, not from a guess.

Step 3: human review

Before committing, review the test like a colleague's pull request. Do the assertions check a business outcome, or just that a click happened? Does the error case also check that the user is not logged in? Is an edge case missing (empty field, locked account)? Run the test yourself, then make it fail once on purpose to prove it catches a regression.

Playwright MCP, Playwright CLI or Test Agents: which one?

Microsoft now offers three ways for an AI to work with Playwright. They are not mutually exclusive, but they target different uses.

The Playwright MCP README is explicit: for a coding agent, the CLI with Skills is often the better choice because each call stays short; MCP stays relevant when the agent has to reason over page structure for a long time with persistent state.

The Playwright Test Agents are set up in an existing project:

npx playwright init-agents --loop=claude
# or: --loop=vscode, --loop=opencode

For Claude Code, the command writes agent definitions in .claude/agents/ and a .mcp.json file that starts npx playwright run-test-mcp-server. The planner explores the app and writes a Markdown test plan, the generator turns the plan into test files, and the healer runs the suite and repairs failing tests; as a last resort it marks a test test.fixme() with a comment explaining why. Re-run the command after each Playwright upgrade to get the latest instructions.

Limits and good practices

What it changes for testers

Playwright MCP does not replace the tester; it shifts the work. Less time goes into writing selectors and boilerplate, more into designing test cases, choosing assertions, preparing data and reviewing code. The skills that matter most are the ones that do not automate: test design techniques (equivalence partitions, boundary values, decision tables), business understanding, and the judgement to tell whether a test really protects against a regression.

You also need to read and fix TypeScript: a tester who does not understand the generated code can neither review nor maintain it. That is why we teach test design and Playwright fundamentals first, then AI applied to testing; see our article on AI and machine learning for test automation. Still choosing a tool? Our Playwright vs Cypress comparison explains the trade-offs, and our CI/CD guide shows how to run the resulting tests in a pipeline.

Frequently asked questions

Written with AI assistance; commands and options were checked against the official Playwright MCP and Playwright documentation. A French version of this guide is available: Playwright MCP : tester avec l'IA.