Playwright MCP Server Tutorial 2026: Step-by-Step From Zero to First AI Test

The Playwright MCP Server tutorial you are about to follow is designed for one kind of reader: someone who has heard about the Model Context Protocol, knows it can make Claude AI write and run browser tests, but has never actually set it up. No prior MCP experience required. No guesswork. Just concrete commands, expected outputs, and explanations of what each step does and why.

By the end of this tutorial, you will have a working MCP Server connected to Claude, and you will have generated, executed, and iterated on a real Playwright test — all without writing a single line of test code manually. If you want a deeper conceptual understanding first, read what the Playwright MCP Server is before continuing.

What Is the Playwright MCP Server? (30-Second Explainer)

The Playwright MCP Server is a bridge between an AI assistant (like Claude) and the Playwright browser automation framework. MCP stands for Model Context Protocol — an open standard that lets AI models interact with external tools in a structured, secure way.

In practical terms: you install a small server on your machine. Claude connects to it. When you ask Claude to "test the login flow on my app," Claude sends commands to the MCP Server, which launches a real browser using Playwright, interacts with your application, captures results, and sends everything back to Claude for analysis.

The result? You describe tests in English. Claude writes the code, runs it through the MCP Server, and reports back — including screenshots, error traces, and suggested fixes. It is the fastest way to go from "I want to test this" to "the test is passing" in 2026.

Prerequisites Before You Start

Before you touch any MCP configuration, make sure you have these four things ready:

• Node.js v18 or later — The MCP Server runs on Node. Download the LTS version from nodejs.org. Verify with node --version in your terminal.
• npm (comes with Node.js) — You will use npm to install the MCP Server package. Verify with npm --version.
• Claude Desktop or Claude Code — You need a Claude AI client that supports MCP connections. Claude Desktop (with a Pro or Max subscription) or Claude Code (Anthropic's CLI) both work.
• A web application to test — Any website works. For this tutorial, we will use a public demo site so you can follow along exactly.

If you are completely new to Playwright itself, the Playwright for beginners guide covers the fundamentals. But you do not need to master Playwright before starting this tutorial — that is the entire point of the MCP Server.

Step 1 — Install Playwright and Configure the MCP Server

Open your terminal and create a fresh project directory. Then initialize Playwright and install the MCP Server package:

# Create project directory
mkdir playwright-mcp-tutorial
cd playwright-mcp-tutorial

# Initialize a new Playwright project
npm init playwright@latest
# When prompted: select TypeScript, tests folder, GitHub Actions: No
# This installs Playwright + browser binaries automatically

# Install the Playwright MCP Server
npm install @anthropic/playwright-mcp-server

# Verify installation
npx playwright --version
# Expected output: Version 1.x.x

The npm init playwright@latest command does three things: it installs the Playwright test runner, downloads Chromium/Firefox/WebKit browser binaries, and scaffolds a basic project structure with a playwright.config.ts file and an example test.

The @anthropic/playwright-mcp-server package is the bridge that Claude will connect to. It exposes Playwright's browser capabilities as MCP tools — navigation, clicking, typing, screenshots, assertions, and more.

Step 2 — Connect Claude Desktop (or Claude Code) to MCP Server

Now that the MCP Server is installed, you need to tell Claude where to find it. This is a one-time configuration step.

Option A: Claude Desktop

Open Claude Desktop's settings file. The location depends on your operating system:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Add the following MCP Server configuration to the file. If the file does not exist yet, create it with exactly this content:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@anthropic/playwright-mcp-server"
      ],
      "cwd": "/absolute/path/to/playwright-mcp-tutorial"
    }
  }
}

Important: Replace /absolute/path/to/playwright-mcp-tutorial with the actual full path to your project directory. On macOS, that might be /Users/yourname/playwright-mcp-tutorial. On Windows, it would be C:\\Users\\yourname\\playwright-mcp-tutorial.

Option B: Claude Code

If you are using Claude Code (Anthropic's CLI), create a .mcp.json file in your project root instead:

• Create the file at playwright-mcp-tutorial/.mcp.json
• Use the same JSON structure as above
• Claude Code reads this file automatically when you open the project

After saving the configuration, restart Claude Desktop (or re-enter the project directory in Claude Code). When Claude reconnects, it will detect the MCP Server and the Playwright tools will become available. You will see a small tools indicator in the Claude interface confirming the connection.

Step 3 — Write Your First AI-Generated Playwright Test

This is where the magic happens. With the MCP Server connected, you do not write test code — you describe what you want to test, and Claude generates and runs it for you.

Open Claude Desktop (or Claude Code) and type a prompt like this:

Example prompt:

"Navigate to https://demo.playwright.dev/todomvc and test the following: add three todo items ('Buy groceries', 'Write tests', 'Ship feature'), mark the second one as complete, filter to show only active items, and verify that only two items are visible."

Claude will use the MCP Server to:

1. Launch a browser instance via Playwright
2. Navigate to the demo application
3. Perform each action you described (adding items, checking one off, filtering)
4. Take screenshots at key steps
5. Verify the expected outcome
6. Generate the equivalent Playwright test code as a .spec.ts file

Here is what the generated test file typically looks like:

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

test('add todos, complete one, filter active', async ({ page }) => {
  // Navigate to the TodoMVC demo app
  await page.goto('https://demo.playwright.dev/todomvc');

  // Add three todo items
  const input = page.getByPlaceholder('What needs to be done?');
  await input.fill('Buy groceries');
  await input.press('Enter');
  await input.fill('Write tests');
  await input.press('Enter');
  await input.fill('Ship feature');
  await input.press('Enter');

  // Mark the second item as complete
  await page.getByRole('checkbox').nth(1).check();

  // Filter to show only active items
  await page.getByRole('link', { name: 'Active' }).click();

  // Verify only two items are visible
  await expect(page.getByTestId('todo-item')).toHaveCount(2);
});

Notice what happened: you described the test in one sentence. Claude generated clean, idiomatic Playwright code using modern locator strategies (getByRole, getByPlaceholder, getByTestId) — not brittle CSS selectors or XPath. The test includes comments, uses async/await properly, and follows Playwright best practices.

Step 4 — Run the Test and Review Results

You have two options for running the generated test:

Option 1: Ask Claude to run it. Simply say "run the test" in your Claude conversation. The MCP Server will execute npx playwright test and return the results — including pass/fail status, execution time, and any error output.

Option 2: Run it yourself in the terminal. Navigate to your project directory and run:

• npx playwright test — runs all tests in headless mode
• npx playwright test --headed — runs with a visible browser window so you can watch
• npx playwright test --ui — opens Playwright's interactive UI mode with step-by-step debugging

When the test passes, you will see output like:

Running 1 test using 1 worker
1 passed (2.1s)

If it fails, Playwright generates an HTML report with screenshots and trace files. Run npx playwright show-report to open it in your browser. This report shows exactly which step failed, what the page looked like at that moment, and the full error stack trace.

For a deeper dive into Playwright's code generation features, see the Playwright codegen tutorial.

Step 5 — Iterate: Ask Claude to Fix and Improve Tests

This is where the MCP Server workflow becomes dramatically more productive than writing tests manually. When something goes wrong — or when you want to expand coverage — you simply talk to Claude.

Scenario 1: A test fails. Paste the error into Claude or say "the todo test is failing, can you investigate?" Claude will use the MCP Server to re-run the test, capture the current page state, analyze the DOM, and either fix the locator or adjust the assertion. Most failures are resolved in a single iteration.

Scenario 2: You want more coverage. Say something like "add a test that verifies the 'Clear completed' button removes checked items." Claude generates the new test, adds it to the spec file, and runs it — all without you opening an editor.

Scenario 3: You want better structure. Ask Claude to "refactor these tests to use a Page Object Model." Claude will create a separate page object class, move locators and actions into it, and update the test file to use the new abstraction. This is the kind of architectural improvement that takes beginners hours to learn and implement — Claude does it in seconds.

The key insight: the MCP Server is not a one-shot code generator. It is an iterative development environment where Claude sees your project files, understands your test results, and continuously improves the test suite based on your feedback. For more on how Claude AI integrates with Playwright beyond the MCP Server, read about using Claude AI with Playwright MCP.

Common Errors and How to Fix Them

Every tutorial should prepare you for what goes wrong. Here are the two most common issues beginners hit, and exactly how to fix them.

MCP Server Not Connecting

Symptom: Claude does not show Playwright tools in the interface, or says "MCP Server not found" when you try to use browser commands.

Causes and fixes:

• Wrong cwd path: The most common cause. Open your config file and verify the path is absolute and points to the directory containing node_modules. Run ls /your/path/node_modules/@anthropic to confirm the package is there.
• Claude not restarted: After editing the config file, you must fully quit and reopen Claude Desktop. Simply closing the window is not enough on macOS — use Cmd+Q.
• Node.js not in PATH: If you installed Node via nvm or a version manager, Claude Desktop might not find npx. Add the full path to npx in the command field: e.g., /Users/you/.nvm/versions/node/v20.x.x/bin/npx.
• Firewall or antivirus blocking: Some corporate security software blocks local server processes. Temporarily disable it to test, then whitelist the Node process.

Tests Failing After Generation

Symptom: Claude generates a test, but it fails when you run it independently with npx playwright test.

Causes and fixes:

• Timing differences: The MCP Server runs tests with the browser visible, which can be slightly slower than headless mode. Add await page.waitForLoadState('networkidle') before assertions if the page loads external resources.
• Dynamic content: If the page content changes between runs (timestamps, random data), ask Claude to use more resilient assertions — toContainText() instead of exact string matches.
• Browser version mismatch: Run npx playwright install to ensure you have the latest browser binaries matching your Playwright version.
• Missing test dependencies: If Claude used a helper function or fixture, make sure the generated code was saved completely. Ask Claude to "show me the full test file" to verify nothing was truncated.

What to Learn Next After This Tutorial

You have completed the core workflow: install, configure, connect, generate, run, iterate. Here is where to go from here to build real-world testing skills:

• Advanced MCP Server configuration — Learn how to set browser launch options, configure viewport sizes, and enable video recording. The MCP Server configuration reference covers every setting.
• Page Object Model — As your test suite grows, organizing tests with page objects keeps them maintainable. Ask Claude to refactor your tests, or study the pattern in our course curriculum.
• API testing with Playwright — Playwright can test REST APIs alongside browser tests. Use the MCP Server to generate API tests from your endpoint documentation.
• CI/CD integration — Run your AI-generated tests automatically on every pull request using GitHub Actions. The course covers this end-to-end.
• Visual regression testing — Use Playwright's screenshot comparison to catch unintended UI changes. The MCP Server can generate baseline screenshots and comparison tests.

Each of these topics is covered in depth in the Playwright + Claude AI & MCP Server course, with hands-on projects and real-world scenarios that build on the foundation you just created in this tutorial.

Frequently Asked Questions

Ready to Master Playwright + MCP Server?

You just went from zero to a working AI-powered Playwright test in five steps. But this tutorial only scratches the surface. The full Playwright + Claude AI & MCP Server course on Udemy covers advanced MCP configuration, Page Object Model with AI, API testing, visual regression, CI/CD pipelines, and real-world projects that prepare you for production QA work.

Enroll on Udemy — Start Building AI Tests Today

Meet Your Instructor

Asim Noaman

Senior QA Automation Engineer & AI Testing Specialist

With years of hands-on experience building test automation frameworks for production applications, Asim specializes in combining traditional QA methodologies with cutting-edge AI tools. He has helped teams adopt Playwright and AI-driven testing workflows to ship faster with fewer bugs.

Udemy Instructor Published course author

Playwright + AI Expert Specialized in AI-powered QA

Production Experience Enterprise-grade frameworks

Connect on LinkedIn