How to Add Playwright MCP to Claude Code: Setup, Config, and Troubleshooting

If you're using Claude Code to build and ship software, you've probably hit the same wall: you can generate backend logic, write API routes, and refactor components at speed, but verifying that your UI actually works still requires you to open a browser and click through things manually. The Playwright MCP server changes that entirely.

With the Playwright MCP Claude Code integration, your AI agent can control a real browser, navigate your app, interact with every element, take screenshots, run end-to-end tests, and extract data, all from a natural language prompt. If you want to get the most out of Claude Code as a whole, the How to Master Claude Code series covers the full workflow from setup to advanced agent automation. This guide walks through everything about Playwright MCP: what the integration is, why it matters, how to set it up, and the practical workflows that will make it part of your daily development process.

What Is the Playwright MCP Server?

The Playwright MCP server is a Model Context Protocol server that gives Claude Code direct control over web browsers using Microsoft's Playwright library. MCP, the open standard created by Anthropic, allows AI agents to communicate with external tools and services. In this case, it bridges Claude Code and a live Chromium (or Firefox, or WebKit) browser instance.

Unlike screenshot-based approaches where an AI guesses what to click from a pixel grid, the Playwright MCP server works through accessibility tree snapshots, structured data that describes every interactive element on a page with unique, stable references. This means Claude Code gets clean, deterministic information: "there is a button labeled Submit at this position in the DOM," not "there appears to be a button somewhere in the bottom-right area."

The result is browser automation that is faster, more reliable, and far less prone to the hallucination errors that plague coordinate-based approaches.

According to a 2025 State of Software Quality Report surveying over 1,400 QA professionals, 72% of QA professionals actively leverage AI for test generation and script optimization, with 82% affirming its critical future importance. The infrastructure to support that shift, tools like the Playwright MCP server, is now mature and production-ready.

Why This Integration Matters

Before Playwright MCP, AI-assisted browser testing meant one of two things: you wrote the test scripts yourself and asked the AI to review them, or you used vision-based agents that were slow, fragile, and expensive on tokens.

The Playwright MCP server gives Claude Code genuine browser agency. You describe what you want in plain language and the agent executes it against a real browser, handling navigation, element interaction, assertions, and reporting. As Debbie O'Brien, Principal Technical Program Manager at Microsoft and Playwright advocate, put it: "The MCP server can do what you would have done yourself as a manual tester." The practical implications are significant:

• You can describe a user flow in one prompt and get a working E2E test back
• You can ask Claude to verify a deployment by checking specific live URLs
• You can have Claude reproduce a bug report by following the exact steps described
• You can generate and run visual regression checks without writing a single line of test code

Playwright MCP is part of a growing ecosystem of MCP servers that extend what Claude Code can do. If you're also working with design files, the Figma MCP Claude Code integration lets you go from design frame to production-ready component in the same agentic workflow.

Playwright MCP Server Setup with Claude Code

Setting up the Playwright MCP server takes under five minutes. There are two implementations worth knowing: the official Microsoft Playwright MCP (@playwright/mcp) and the community ExecuteAutomation MCP (mcp-playwright). Both work well with Claude Code. This guide uses the Microsoft implementation.

Step 1: Install Node.js 18 or Later

The Playwright MCP server requires Node.js 18+. Verify your version:

node --version

If you're below 18, update via your preferred Node version manager before continuing.

Step 2: Add the Server with One Command

The fastest way to add Playwright MCP to Claude Code is the built-in claude mcp add command. Run this from your terminal:

claude mcp add playwright -- npx @playwright/mcp@latest

That's it. Everything after the -- is the command that runs the server, and Claude Code stores the configuration for you. By default the server is added at local scope: it's saved in ~/.claude.json and only loads in the project you ran the command from. Two other scopes are worth knowing:

• --scope user makes the server available in all your projects (great for a general tool like Playwright)
• --scope project writes the config to a .mcp.json file at the project root so your whole team gets it via version control

claude mcp add playwright --scope user -- npx @playwright/mcp@latest

If you prefer to share the setup with your team, the generated .mcp.json looks like this:

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

For a headless setup (no visible browser window, useful for CI/CD), append the --headless flag to the server args:

claude mcp add playwright -- npx @playwright/mcp@latest --headless

For a specific browser (the --browser flag accepts chrome, firefox, webkit, or msedge):

claude mcp add playwright -- npx @playwright/mcp@latest --browser firefox

For a Docker or remote server setup where you need HTTP transport, start the standalone server first:

npx @playwright/mcp@latest --port 8931

Then point Claude Code at it:

claude mcp add --transport http playwright http://localhost:8931/mcp

Step 3: Verify the Integration

First confirm the server is registered and healthy:

claude mcp list

You should see playwright in the list with a connected status (you can also run /mcp inside a Claude Code session to inspect it). Then test the connection with a simple prompt:

Use playwright mcp to open a browser and navigate to example.com.
Take a screenshot and describe what you see.

If the setup is correct, a browser window will open (unless you configured headless mode), Claude Code will navigate to the page, capture a screenshot, and return a description of the content.

Note: Be explicit about "playwright mcp" the first time in a session, Claude Code's tool routing will then keep it active for the conversation. For more on how to get Claude Code to follow complex instructions reliably, Claude Code Plan Mode is worth reading before you run large testing sessions.

The Full Capability Set

The Playwright MCP server exposes a comprehensive set of browser automation tools. Here is what Claude Code can do once the integration is active.

Navigation and Page Interaction

Claude Code can navigate to any URL, go back and forward in browser history, and reload pages. It can click buttons, fill text fields, select dropdown options, check checkboxes, and trigger any interactive element the accessibility tree exposes.

Navigate to http://localhost:3000, fill the email field with test@example.com,
enter "password123" in the password field, and click the Sign In button.

Screenshots and Visual Inspection

Claude Code can capture full-page screenshots or screenshots of specific elements. This is invaluable for visual QA, you can ask Claude to compare two states of your UI, flag layout regressions, or document what a page looks like before and after a change.

Take a screenshot of the dashboard page and describe any visual issues
you notice with the layout on a 1280x800 viewport.

JavaScript Execution

Claude Code can execute arbitrary JavaScript in the browser context, giving it access to the DOM, localStorage, network state, and any client-side data.

Execute JavaScript to read the value of localStorage.getItem('auth_token')
and confirm it's set after login.

Waiting and Timing

The server handles waits for specific elements to appear, network requests to complete, or page navigation to finish. This eliminates the flakiness that makes browser tests frustrating to maintain.

Navigate to /checkout, wait for the order summary to load, then verify
the subtotal displays correctly before clicking Confirm Order.

Data Extraction and Scraping

Claude Code can extract structured data from any web page, product listings, search results, table data, or anything else visible in the browser.

Navigate to our pricing page and extract all plan names, prices, and
feature lists into a JSON structure.

Practical Workflows

Workflow 1: End-to-End Test Generation

This is the highest-value use case. Describe a user flow and ask Claude Code to test it, then generate a Playwright test script from the results.

Test the complete signup flow on http://localhost:3000:
1. Navigate to /signup
2. Fill in the name, email, and password fields
3. Click the Create Account button
4. Verify the user lands on the /dashboard page
5. Confirm the welcome message includes the user's name

After testing, generate a Playwright test script I can add to my test suite.

Workflow 2: Deployment Validation

After deploying to staging or production, ask Claude Code to verify the live URL behaves correctly before you consider the deployment done.

Check our staging deployment at https://staging.myapp.com:
- Confirm the homepage loads without errors
- Verify the navigation links all respond
- Check that the login form is present and the submit button is clickable
- Take a screenshot of the homepage for the deployment record

Workflow 3: Bug Reproduction

When a user reports a bug, paste the reproduction steps directly into Claude Code and have it execute them.

A user reported they can't add items to cart when browsing on mobile viewport.
Using playwright mcp, set the viewport to 390x844, navigate to our product page
at /products/widget-pro, and try to add the item to cart. Document what happens
and whether the bug is reproducible.

Workflow 4: Visual Regression Check

Before and after a CSS refactor, use Claude Code to capture screenshots and identify visual differences.

Navigate to each page in this list and take a screenshot:
/, /about, /pricing, /contact

Save the screenshots and flag any pages where the layout looks broken
or content appears misaligned.

Troubleshooting Common Playwright MCP Issues

Most Playwright MCP problems fall into a handful of categories. Here is how to diagnose and fix each one.

The server doesn't appear or fails to connect

Run claude mcp list in your terminal (or /mcp inside a session) to see the server's status. If playwright isn't listed at all, the add command probably ran in a different project: local scope (the default) ties the server to the directory you ran claude mcp add from. Re-add it with --scope user to make it available everywhere.

If it's listed but failing to connect, check these in order:

1. Node version. The server requires Node.js 18+. Run node --version and upgrade if needed. An old Node silently breaks npx @playwright/mcp@latest.
2. Run the server manually. Execute npx @playwright/mcp@latest directly in your terminal. If it errors there, you'll see the actual message instead of a generic connection failure.
3. Startup timeout. On a first run, npx has to download the package, which can exceed Claude Code's default MCP startup timeout. Launch with a longer window: MCP_TIMEOUT=10000 claude gives the server 10 seconds to boot.
4. Duplicate definitions. If you added the server at multiple scopes, Claude Code uses the highest-precedence one (local beats project beats user). Run claude mcp get playwright to see exactly which config is active, and claude mcp remove playwright to clear a broken entry before re-adding it.

The browser binary is missing

If Claude reports that the browser is not installed (a "browser not found" or "Chromium distribution not found" style error), the Playwright browser binaries haven't been downloaded on this machine yet. Install them manually:

npx playwright install chromium

Swap chromium for chrome, firefox, or webkit to match whatever you set with --browser. Note that --browser chrome and --browser msedge use the actual Chrome/Edge channel, so the corresponding browser must be installed on the machine.

Headless vs headed: pick the right mode

The server runs headed by default: a real browser window opens on your screen. That's ideal while developing because you can watch what the agent does. It fails, however, in any environment without a display: CI runners, Docker containers, SSH sessions, and remote dev boxes. In those contexts, add --headless to the server args or the launch will error out.

Two related gotchas:

• Docker and restricted Linux environments often can't run Chromium's sandbox. If the browser crashes on launch with sandbox errors, add --no-sandbox to the args.
• The official Docker image (mcr.microsoft.com/playwright/mcp) only supports headless Chromium, so don't fight it trying to get a headed Firefox running in a container.

The browser profile is locked

By default the server uses a persistent profile (stored under ~/Library/Caches/ms-playwright/ on macOS, ~/.cache/ms-playwright/ on Linux), which keeps you logged in between sessions. The catch: only one instance can use that profile at a time. If you run multiple Claude Code sessions with Playwright MCP simultaneously, the second one will fail to launch the browser. Fix it by adding --isolated to the args, which gives each session its own in-memory profile (you lose persisted logins), or point each instance at its own directory with --user-data-dir.

Actions time out on slow pages

The server defaults to a 5 second action timeout and a 60 second navigation timeout. If your dev server does slow cold starts or your app has heavy pages, raise them with --timeout-action 15000 and --timeout-navigation 120000 in the server args. Also make sure your local app is actually running before the test prompt: Claude can't wait for a server that was never started.

Tips for Reliable Results

Be explicit about the MCP server on first use. Claude Code routes tools contextually, so saying "use playwright mcp to..." the first time ensures the right tools load. After that, the context is established.

Use headless mode for automated pipelines. If you're running Claude Code in a CI context or a remote environment without a display, add --headless to your configuration. This also speeds up execution since there's no rendering overhead.

Specify viewport sizes for responsive testing. The default viewport may not surface mobile-specific bugs. Explicitly request 390x844 for iPhone, 768x1024 for tablet, or 1440x900 for desktop when viewport matters.

Ask for structured output when extracting data. Rather than asking Claude to "find the prices," prompt it to "extract all prices as a JSON array." Structured requests produce structured, usable output.

Combine with test file generation. The real productivity multiplier is asking Claude Code to both execute a test flow and write the Playwright .spec.ts file that automates it permanently. You get immediate validation plus a regression guard in one prompt.

Build on This Foundation

The Playwright MCP server is one piece of a larger AI-driven development workflow. Combined with Claude Code's ability to write, refactor, and review code, it closes the loop between development and quality assurance. You write the feature, ask Claude Code to test it against a live browser, and iterate, all without switching context.

MCP servers are most powerful when you treat them as building blocks. You can even build a custom MCP server to encode your own team's workflows and domain knowledge, turning your specific expertise into reusable tools that any agent can call. The same configuration approach you used for Playwright MCP applies directly. For a deeper look at the full MCP ecosystem and how to connect Claude Code to services like Notion, see the Claude Code Notion MCP guide.

According to the 2025 Stack Overflow Developer Survey, 80% of developers now use AI tools in their workflows, but those who pair AI code generation with AI testing capabilities are the ones compounding the productivity gains.

If you want to go deeper on building with Claude Code, including how to structure your projects with MCP servers, write effective prompts for complex tasks, and ship production-ready apps faster, explore the AI-powered design-to-code workflows series or the full curriculum at vibecodingacademy.ai.