Browse all tutorials →
MCP Server Updated November 19, 2026 14 min read

Playwright MCP + Claude Code: Setup, Tests & Debugging (2026)

Playwright MCP gives Claude Code a real browser. Add it with one command, then have Claude Code open your app, read the page and write Playwright tests that use real selectors. This guide covers setup, config scopes, test generation, debugging, custom tools and the errors people hit most.

Quick answer: to use Playwright MCP with Claude Code, run claude mcp add playwright npx @playwright/mcp@latest in your project folder. Then start claude, type /mcp to confirm that playwright is connected, and ask Claude Code to open a URL and write a test. You need Node.js 20 or newer.

Claude Code is Anthropic's AI coding agent that runs in your terminal. Pair it with the Playwright MCP Server and it can open a real browser, move through your application, read the live page and write Playwright tests, all without leaving the terminal.

This guide covers the whole workflow, from the first install to custom tools. By the end, Claude Code will be generating, running and debugging Playwright tests against your live application.

Prefer to learn it on video? The Playwright + Claude AI & MCP Server course on Udemy teaches Playwright in JavaScript from scratch, then Claude Code and the Playwright MCP Server step by step.


What Is the Playwright MCP Server?

The Model Context Protocol (MCP) is an open standard created by Anthropic that lets AI models interact with external tools. Think of it as a USB port for AI — any tool that implements the MCP protocol can plug into Claude and extend what it can do.

Official support: the Playwright MCP README (github.com/microsoft/playwright-mcp) has install steps for Claude Code, Cursor, VS Code and other MCP clients. For Claude Code, setup is a single claude mcp add command.

The Playwright MCP Server is an official tool built by the Playwright team that exposes browser automation capabilities through this protocol. When connected to Claude Code, it gives the AI direct access to:

  • Browser navigation — go to any URL, click links, fill forms
  • DOM inspection — read the accessibility tree, find elements, check text content
  • Screenshots — capture what the page actually looks like
  • Interaction — click buttons, type into inputs, select dropdowns, hover over menus
  • Page state — read console logs, network requests, cookies, localStorage

Without MCP, Claude Code can write Playwright tests based on your descriptions — but it's guessing at selectors and page structure. With MCP, Claude sees your actual application and writes tests that match the real DOM, real selectors, and real user flows. Once tests are generated, they run as standard Playwright end-to-end tests — no MCP dependency at runtime.

Key distinction: MCP is the protocol. Playwright MCP Server is one specific implementation of that protocol. You can have multiple MCP servers connected to Claude Code simultaneously — for example, Playwright for browser access and a custom server for database operations.

New to the Playwright MCP Server? Start with the Playwright MCP Server tutorial: install it, connect it to Claude and generate your first test, then come back here.

Prerequisites

Before starting, make sure you have these three things installed:

  1. Node.js 20 or newer. The Playwright MCP README lists Node 20 as the minimum. Check your version with node --version.
  2. Claude Code, Anthropic's terminal agent. Install it with the native installer (curl -fsSL https://claude.ai/install.sh | bash) or with npm (npm install -g @anthropic-ai/claude-code), then sign in with your Claude subscription or an API key.
  3. A Playwright project — if you don't have one yet, run npm init playwright@latest to scaffold a new project with TypeScript, test examples, and config.
Terminal — verify all prerequisites
# Node.js 20 or newer
node --version

# Claude Code is installed and on your PATH
claude --version

# Playwright is installed in your project
npx playwright --version

If any of these commands fail, install the missing dependency before continuing. The rest of this guide assumes all three are working. If you prefer to use Claude Desktop instead of the CLI, see our Playwright MCP Server + Claude AI setup guide for the GUI-based workflow.

Installing the Playwright MCP Server

The Playwright MCP Server is distributed as the @playwright/mcp npm package. You have three installation approaches:

Method Command Best for
On-demand (npx) npx @playwright/mcp@latest Default. Always runs the latest version, no install step.
Global install npm install -g @playwright/mcp Faster startup (~2s saved). Good if you use MCP daily.
Project dependency npm install --save-dev @playwright/mcp Pin a version for team consistency. Committed to package.json.

For most people, the npx approach is the right default. It pulls the latest version automatically and needs no install step. You don't start the server yourself: Claude Code launches it when a session starts and stops it when the session ends.

Adding Playwright MCP to Claude Code

Claude Code has a built-in claude mcp command for registering MCP servers. Run this from your Playwright project folder:

Terminal — the one command you need
claude mcp add playwright npx @playwright/mcp@latest

That's the command from the official Playwright MCP README. It registers a server named playwright that Claude Code starts with npx.

Choose a scope

The --scope flag decides where the configuration is saved and who gets it:

Scope Command Stored in Use it when
Local (default) claude mcp add playwright ... ~/.claude.json, for this project only Only you need it, in this project
Project claude mcp add --scope project playwright ... .mcp.json in the project root Your whole QA team should get it from git
User claude mcp add --scope user playwright ... ~/.claude.json, for all projects You want it in every project

For a team, commit .mcp.json. Here is what the project-scoped file looks like, so you can also write it by hand:

.mcp.json (project root)
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    }
  }
}

Useful Playwright MCP flags

Anything after the package name is passed to the Playwright MCP server. These are the flags QA engineers use most:

  • --headless runs the browser without a window. The default is headed, so you can watch Claude work.
  • --browser firefox (or chrome, webkit, msedge) picks the browser.
  • --isolated keeps the browser profile in memory, so cookies and logins don't carry over between sessions.
Terminal — headless, isolated, shared with the team
claude mcp add --scope project playwright -- npx @playwright/mcp@latest --headless --isolated

The -- separates Claude Code's own options from the server command, so flags like --headless reach Playwright MCP instead of claude.

Verify the connection

Start a new Claude Code session and check that the MCP server is recognized:

Terminal
# Start Claude Code in your project directory
cd /path/to/your/playwright-project
claude

# Inside Claude Code, check connected MCP servers
/mcp

# Expected: "playwright" listed as a connected server with available tools

# Or check from your shell, outside a session
claude mcp list

If Playwright appears in the /mcp output with tools like browser_navigate, browser_snapshot and browser_click, setup is complete. To undo it, run claude mcp remove playwright.

Common mistake: putting mcpServers in .claude/settings.json. Claude Code doesn't load MCP servers from that file. Use claude mcp add or .mcp.json, then start a new session, because Claude Code reads MCP config at startup.

Your First AI-Generated Test

With MCP connected, let's generate a real test. This walkthrough uses the Playwright docs site as a target, but substitute your own application URL.

1

Describe the test in plain English

Tell Claude Code what you want to test. Be specific about the page, the user action, and the expected result.

2

Claude navigates and inspects the page

Claude uses the MCP Server to open the URL in a real browser, read the accessibility tree, and understand the page structure before writing any code.

3

Claude writes the test with real selectors

Because Claude can see the actual DOM, it uses getByRole, getByLabel, and getByText selectors that match your real UI — not guesses.

4

Run the test to verify

Claude can run npx playwright test directly and confirm the test passes. If it fails, it debugs immediately.

Here's what the conversation looks like in practice:

Claude Code session
# Your prompt:
Navigate to https://playwright.dev and write a Playwright test that verifies
the "Get Started" button in the hero section links to the /docs/intro page.
Use TypeScript and save it to tests/homepage.spec.ts.

# Claude's workflow (visible in the session):
# 1. browser_navigate → https://playwright.dev
# 2. browser_snapshot → reads the accessibility tree
# 3. Identifies the "Get started" link with role="link"
# 4. Writes the test file
# 5. Runs: npx playwright test tests/homepage.spec.ts
# 6. Reports: 1 passed

The generated test will look something like this:

tests/homepage.spec.ts
import { test, expect } from '@playwright/test';

test('Get Started button links to intro docs', async ({ page }) => {
  await page.goto('https://playwright.dev');

  const getStarted = page.getByRole('link', { name: 'Get started' });
  await expect(getStarted).toBeVisible();
  await getStarted.click();

  await expect(page).toHaveURL(/\/docs\/intro/);
});

Notice the selector quality. Claude used getByRole('link', { name: 'Get started' }) because it read the actual accessibility tree via MCP. Without MCP, it might have guessed .hero-button or a[href="/docs/intro"] — selectors that break when the CSS or HTML changes.

Browser Context: How Claude Sees Your App

Understanding what Claude can and cannot see through MCP is critical for writing effective prompts.

When Claude calls browser_snapshot, it receives the page's accessibility tree — a structured representation of every interactive element, heading, text block, image (with alt text), form field, and ARIA landmark on the page. This is the same tree that screen readers use.

Example: what Claude sees after browser_snapshot
# Simplified accessibility tree output
- navigation "Main"
  - link "Home"
  - link "Docs"
  - link "API"
  - link "Community"
  - link "Get started"
- heading "Playwright" [level=1]
- text "Reliable end-to-end testing for modern web apps"
- link "Get started" [focused]
- link "Star on GitHub"
- heading "Any browser. Any platform." [level=2]
...

Claude can also:

  • Take screenshots — browser_take_screenshot captures a PNG of the visible viewport, useful for visual verification
  • Read console output — see JavaScript errors, warnings, and logs
  • Inspect network requests — verify API calls, check response status codes
  • Execute JavaScript — run arbitrary JS in the page context for advanced inspection

This means Claude's test generation is grounded in reality. It knows exactly which elements exist, what their accessible names are, and how the page is structured — before it writes a single line of test code.

Generating Tests from Live Pages

The most powerful MCP workflow is having Claude navigate your running application and generate tests from the actual UI. Here's a realistic example:

Claude Code prompt
Navigate to http://localhost:3000/login and generate a complete test suite
for the login page. Cover:
1. Successful login with valid credentials
2. Error message for wrong password
3. Required field validation (empty submit)
4. Password visibility toggle
Save to tests/auth/login.spec.ts using Page Object Model.

Claude will navigate to the login page, snapshot the DOM, identify the email input, password input, submit button, error message container, and visibility toggle. Then it generates a full test suite and a Page Object Model class:

pages/LoginPage.ts (generated by Claude)
import { type Page, type Locator } from '@playwright/test';

export class LoginPage {
  readonly emailInput: Locator;
  readonly passwordInput: Locator;
  readonly submitButton: Locator;
  readonly errorMessage: Locator;
  readonly togglePassword: Locator;

  constructor(private page: Page) {
    this.emailInput = page.getByLabel('Email');
    this.passwordInput = page.getByLabel('Password');
    this.submitButton = page.getByRole('button', { name: 'Sign in' });
    this.errorMessage = page.getByRole('alert');
    this.togglePassword = page.getByLabel('Show password');
  }

  async goto() {
    await this.page.goto('/login');
  }

  async login(email: string, password: string) {
    await this.emailInput.fill(email);
    await this.passwordInput.fill(password);
    await this.submitButton.click();
  }
}
tests/auth/login.spec.ts (generated by Claude)
import { test, expect } from '@playwright/test';
import { LoginPage } from '../../pages/LoginPage';

test.describe('Login page', () => {
  let loginPage: LoginPage;

  test.beforeEach(async ({ page }) => {
    loginPage = new LoginPage(page);
    await loginPage.goto();
  });

  test('successful login redirects to dashboard', async ({ page }) => {
    await loginPage.login('user@example.com', 'validPassword123');
    await expect(page).toHaveURL('/dashboard');
  });

  test('wrong password shows error message', async () => {
    await loginPage.login('user@example.com', 'wrongPassword');
    await expect(loginPage.errorMessage).toBeVisible();
    await expect(loginPage.errorMessage).toContainText('Invalid credentials');
  });

  test('empty form submission shows validation errors', async () => {
    await loginPage.submitButton.click();
    await expect(loginPage.emailInput).toHaveAttribute('aria-invalid', 'true');
  });

  test('password toggle reveals password text', async () => {
    await loginPage.passwordInput.fill('secret123');
    await loginPage.togglePassword.click();
    await expect(loginPage.passwordInput).toHaveAttribute('type', 'text');
  });
});

Every selector in this code was derived from the live DOM — not guessed from a description. The getByLabel('Email'), getByRole('button', { name: 'Sign in' }), and getByRole('alert') selectors match what actually exists on the page.

Debugging Failures with MCP

This is where the MCP + Claude Code combination truly shines. Instead of staring at a stack trace and manually re-running tests, you hand the failure to Claude and let it investigate with a real browser.

The workflow

1

Paste the failing test and error

Copy the test file and the error output from npx playwright test. Give Claude the full context.

2

Claude navigates to the page

Claude opens the same URL in MCP's browser, snapshots the DOM, and compares the expected selectors against what's actually on the page.

3

Claude identifies the root cause

Maybe the button text changed from "Submit" to "Sign in". Maybe a modal now blocks the element. Maybe the page redirects before the element loads. Claude can see all of this.

4

Claude rewrites and re-runs the test

The fix is applied, the test is executed, and Claude confirms it passes — all in one conversation.

Example prompt for debugging:

Claude Code prompt
This test is failing. Navigate to http://localhost:3000/checkout
and figure out why. Here's the error:

Error: locator.click: Error: strict mode violation:
  getByRole('button', { name: 'Place order' }) resolved to 2 elements

Fix the test in tests/checkout.spec.ts so it targets the correct button.

Claude will navigate to the checkout page, snapshot the DOM, find both "Place order" buttons (perhaps one is in a summary sidebar and one is in a sticky footer), and update the selector to target the correct one — for example, by scoping it to a specific section:

Before (failing)
await page.getByRole('button', { name: 'Place order' }).click();
After (fixed by Claude)
await page.getByRole('region', { name: 'Order summary' })
  .getByRole('button', { name: 'Place order' }).click();

Advanced: Custom MCP Tools for QA

The Playwright MCP Server handles browser automation, but real QA workflows need more — test data setup, database seeding, API mocking, environment resets. You can build custom MCP servers that expose these operations as tools Claude can call.

Why custom tools matter

Imagine telling Claude: "Create a test user with admin permissions, seed 50 products, then test the admin dashboard filtering." Without custom tools, you'd need to set this up manually before running Claude. With a custom MCP server, Claude does it all.

Example: a test data MCP server

mcp-servers/test-data-server.ts
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

const server = new McpServer({ name: 'test-data', version: '1.0.0' });

server.tool(
  'seed_test_user',
  'Create a test user with specified role',
  { email: { type: 'string' }, role: { type: 'string' } },
  async ({ email, role }) => {
    // Insert user into test database
    const user = await db.createUser({ email, role, password: 'TestPass123!' });
    return { content: [{ type: 'text', text: `Created user ${user.id} (${email}, ${role})` }] };
  }
);

server.tool(
  'reset_database',
  'Reset the test database to a clean state',
  {},
  async () => {
    await db.reset();
    return { content: [{ type: 'text', text: 'Database reset complete' }] };
  }
);

const transport = new StdioServerTransport();
await server.connect(transport);

Register it next to Playwright with claude mcp add --scope project test-data -- npx tsx mcp-servers/test-data-server.ts. Your .mcp.json then holds both servers:

.mcp.json — multiple MCP servers
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    },
    "test-data": {
      "command": "npx",
      "args": ["tsx", "mcp-servers/test-data-server.ts"]
    }
  }
}

Now Claude Code can seed data, navigate the browser, and validate the UI — all in a single conversation. This is the foundation of a fully autonomous QA agent.

MCP Server vs Claude Code vs Claude.ai — When to Use Which

These three tools overlap but serve different purposes. Here's when to reach for each:

Playwright MCP Server Claude Code (CLI) Claude.ai (Web)
What it is Browser automation bridge Terminal AI assistant Web chat interface
Browser access Yes — real Chromium/Firefox/WebKit Only via MCP Server No
File system access No Yes — read/write project files No
Run tests No (it's a tool, not a runner) Yes — runs npx playwright test No
Best for Giving AI eyes on your app Full test generation + debugging workflow Quick questions, learning concepts
Ideal workflow Connected to Claude Code as a tool Primary interface for QA automation Planning, code review, documentation

The recommended setup for 2026: Use Claude Code as your primary interface with the Playwright MCP Server connected. This gives you browser access + file system access + terminal execution in a single workflow. Use Claude.ai for planning, conceptual discussions, and code reviews where you don't need live browser interaction. Claude can also generate visual regression tests using toHaveScreenshot() directly from the live page — making pixel-perfect UI testing nearly effortless.

Pro tip: You can also connect the Playwright MCP Server to Claude Desktop (the GUI app) for a more visual experience. See our MCP Server setup guide for Claude Desktop configuration.

Token Usage & Cost Optimization

The Playwright MCP Server provides rich browser context to Claude — but that context has a token cost. Each MCP interaction uses approximately 114K tokens, which includes the DOM snapshot, accessibility tree, page metadata, and tool call overhead.

For comparison, the newer Playwright CLI approach uses approximately 27K tokens per test — a 76% reduction. The trade-off: CLI provides pre-filtered context (less accurate for complex flows) while MCP gives Claude full browser control.

Cost-saving tip: Use MCP Server for interactive debugging and complex test authoring, then switch to CLI for batch generation in CI pipelines. This hybrid approach can reduce token costs by 60-70%. See the full MCP vs CLI token cost comparison.

Troubleshooting Common Issues

If your setup isn't working, find your symptom below. These are the most frequently reported issues with the Playwright MCP + Claude Code combination.

1. MCP server not appearing in /mcp output

Cause: the server was added in a different folder or scope, it was put in .claude/settings.json (which Claude Code doesn't read for MCP), or .mcp.json has a JSON syntax error.
Fix: run claude mcp list from the project folder. If playwright is missing, run claude mcp add playwright npx @playwright/mcp@latest again from that folder. Claude Code also asks you to approve project servers from .mcp.json the first time it sees them. Start a new session after any change.

2. "spawn npx ENOENT" error

Cause: Node.js or npx isn't on the PATH that Claude Code inherits.
Fix: on macOS and Linux, make sure Node is set up in your shell profile (~/.zshrc or ~/.bashrc). On native Windows, run npx through cmd /c, as the Claude Code docs recommend:

Windows fix
claude mcp add --transport stdio playwright -- cmd /c npx @playwright/mcp@latest

3. Timeout when Claude tries to navigate

Cause: The target URL is unreachable — your dev server isn't running, or there's a network/proxy issue.
Fix: Start your dev server first (npm run dev). Verify you can open the URL in a regular browser. If you're behind a corporate proxy, add proxy environment variables to the server's entry in .mcp.json:

.mcp.json with proxy
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"],
      "env": {
        "HTTP_PROXY": "http://proxy.company.com:8080",
        "HTTPS_PROXY": "http://proxy.company.com:8080"
      }
    }
  }
}

4. "Browser executable not found"

Cause: Playwright browsers aren't installed on this machine.
Fix: Run npx playwright install chromium (or npx playwright install for all browsers). On Linux, also run npx playwright install --with-deps to install system-level dependencies.

5. "Permission denied" on macOS

Cause: macOS Gatekeeper blocking the Chromium binary that Playwright downloads.
Fix: Run xattr -cr ~/Library/Caches/ms-playwright to remove the quarantine flag from all Playwright browser binaries. Alternatively, open System Settings → Privacy & Security and approve the blocked application.

macOS permission fix
# Remove quarantine flag from Playwright browsers
xattr -cr ~/Library/Caches/ms-playwright

# Verify Chromium launches
npx playwright open https://example.com

6. MCP server crashes mid-session

Cause: Memory exhaustion (common with many open tabs/contexts) or a version incompatibility.
Fix: Update to the latest version: npx @playwright/mcp@latest. If you installed globally, run npm update -g @playwright/mcp. Start a new Claude Code session — MCP servers are restarted with each session.

7. Claude says "I don't have browser access"

Cause: The MCP server is configured but Claude doesn't know it can use browser tools.
Fix: Run /mcp to confirm the server is connected. If it is, explicitly ask Claude to use it: "Use the Playwright MCP Server to navigate to [URL]." Claude sometimes needs a nudge to invoke MCP tools versus writing code directly.

Ready to master Playwright + Claude AI?

Hands-on Udemy course: Playwright in JavaScript from scratch, Claude Code, the Playwright MCP Server and AI agents.

Enroll on Udemy →

Frequently Asked Questions

Can Claude Code generate Playwright tests without MCP Server?

Yes, but the quality is lower. Without MCP, Claude generates tests based solely on your descriptions and any code you paste. With MCP, Claude navigates your live app, reads the actual DOM, and writes tests with selectors that match real elements — producing significantly more reliable tests.

Is Playwright MCP Server free to use with Claude Code?

The Playwright MCP Server (@playwright/mcp) is completely free and open-source. Claude Code requires an Anthropic API key or a Claude Pro/Team subscription. There is no additional charge for using MCP Server features.

How do I debug a failing test with Claude Code and MCP?

Paste the failing test file and the error output into Claude Code. Ask Claude to navigate to the same page via MCP, inspect the DOM, and find the root cause. Claude will identify the issue (wrong selector, timing, changed UI) and rewrite the test — then run it to confirm the fix.

Does MCP Server work with Claude Code in VS Code terminal?

Yes. Claude Code runs in any terminal, including VS Code's integrated terminal. Run claude mcp add playwright npx @playwright/mcp@latest from your project folder, or commit a .mcp.json, and Playwright MCP is available in every Claude Code session you start from that project.

Can I create custom MCP tools for my QA workflow?

Yes. Build custom MCP servers with the @modelcontextprotocol/sdk package to expose project-specific tools, such as database seeding, test user creation, API mocking and environment resets. Register them next to Playwright with claude mcp add (or in .mcp.json), and Claude can use all of them in one session.

What is the command to add Playwright MCP to Claude Code?

Run claude mcp add playwright npx @playwright/mcp@latest. Add --scope project to save it in .mcp.json for your team, or --scope user to make it available in all your projects. Then check it with /mcp inside Claude Code.

Where can I learn Claude Code with Playwright step by step?

The Playwright + Claude AI & MCP Server course on Udemy starts with Playwright in JavaScript from scratch, then covers Claude Code, the Playwright MCP Server, building a QA AI agent and Playwright Test Agents. For what to look for in any course, see our Claude Code course for testers guide.


Asim Noaman, Playwright and Claude AI course instructor

Asim Noaman

Sr. SQA Manager & AI Automation Engineer

18+ years in QA. Asim currently runs an 80+ engineer QA function at Tkxel and built a Testing Center of Excellence for a major Saudi bank. He builds AI testing agents with Playwright, Claude AI and the MCP Server at work, and teaches the same workflow in his courses.

18+ Years in QA 80+ engineer QA function
Udemy Instructor 4.5★ · 140+ ratings · 570+ students
Anthropic Certificates Claude API · MCP
Connect on LinkedIn

Full profile →

Playwright + Claude AI Course

Learn the Full MCP Server Workflow — End to End

You've seen what the Playwright MCP Server does. The course teaches Playwright in JavaScript from scratch (locators, assertions, hooks and the Page Object Model), then Claude Code, the Playwright MCP Server, your own QA AI agent and Playwright Test Agents.

  • Step-by-step MCP Server installation and Claude AI configuration
  • Generate and refine tests inside Claude using live browser context
  • Handle authentication, dynamic data, and edge cases with AI assistance
  • Claude Code and the Playwright MCP Server for AI test generation
See the Full MCP Course on Udemy →