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:
- Node.js 20 or newer. The Playwright MCP README lists Node 20 as the minimum. Check your version with
node --version. - 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. - A Playwright project — if you don't have one yet, run
npm init playwright@latestto scaffold a new project with TypeScript, test examples, and config.
# 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:
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:
{
"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:
--headlessruns the browser without a window. The default is headed, so you can watch Claude work.--browser firefox(orchrome,webkit,msedge) picks the browser.--isolatedkeeps the browser profile in memory, so cookies and logins don't carry over between sessions.
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:
# 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.
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.
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.
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.
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:
# 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:
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.
# 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_screenshotcaptures 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:
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:
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(); } }
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
Paste the failing test and error
Copy the test file and the error output from npx playwright test. Give Claude the full context.
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.
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.
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:
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:
await page.getByRole('button', { name: 'Place order' }).click();
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
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:
{
"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:
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:
{
"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.
# 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.
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
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.
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