Browse all tutorials →
Setup Guide August 13, 2026 18 min read

Playwright MCP Server Setup for Claude Desktop, VS Code & More (2026)

A complete, hands-on guide to getting Playwright MCP Server running with Claude Desktop, Claude Code, and VS Code. Covers every configuration option, platform-specific fixes, proxy & auth state, and the 10 most common setup errors — so you spend zero time debugging your tooling and all your time generating tests.

TL;DR: Run npx @playwright/mcp@latest, add one JSON block to your Claude config file, and you'll have Playwright MCP Server running in under 5 minutes. The full setup, every config option, and fixes for the 10 most common errors are below. Using Claude Code? Follow the Playwright MCP + Claude Code guide, which uses the one-line claude mcp add setup.

The Playwright MCP Server is the bridge between Claude AI and your running application. Once connected, Claude can navigate to any URL, read the live DOM, interact with elements, and generate production-ready Playwright tests — all from plain English. This is what makes vibe testing with Playwright work: instead of guessing at selectors, Claude reads your real DOM and writes tests that pass on the first run. But you have to get the setup right first.

This guide is laser-focused on the setup. No theory, no conceptual overview — just every command, config file, flag, and fix you need to go from zero to a working MCP connection in under 10 minutes. If you want a conceptual introduction to what MCP is and what it can do, read our Playwright MCP Server + Claude AI overview first.


Who this is for

  • QA engineers and developers connecting Claude to Playwright for the first time
  • Anyone who wants Claude to generate Playwright tests from natural language
  • Teams troubleshooting a broken or incomplete MCP Server connection

Prerequisites

Before you start, verify these are in place:

  1. Node.js 18+ — run node --version to check. If you're below 18, download the LTS version.
  2. A Playwright project — if you don't have one yet: npm init playwright@latest. See our Playwright for beginners guide for a walkthrough.
  3. Claude access — you need one of: Claude Desktop (free tier works for testing), Claude Pro ($20/month for heavier use), Claude Code CLI, or an Anthropic API key.
Terminal — verify prerequisites
# Check Node.js version (must be 18+)
node --version
# v20.15.0  ✓

# Check npm is available
npm --version
# 10.8.1  ✓

# Check npx is available (ships with npm 5.2+)
npx --version
# 10.8.1  ✓

This page covers configuration in depth. For the end-to-end walkthrough, from install to your first generated test, see the Playwright MCP Server tutorial.

Step 1: Install Playwright MCP Server

You have three installation options. Pick the one that fits your workflow:

Method Command When to use
On-demand (npx) npx @playwright/mcp@latest Default choice. No install needed — always runs the latest version.
Global install npm install -g @playwright/mcp Faster startup (~2s vs ~5s). Good if you use MCP daily.
Project dependency npm install --save-dev @playwright/mcp Pin a specific version. Good for teams that need reproducibility.

Recommendation: Start with the npx approach. It always pulls the latest version and requires zero setup. Switch to global install later if the 3-second startup difference matters to your workflow.

To verify the package is accessible, run it directly:

Terminal
# Should start the MCP server and wait for connections
npx @playwright/mcp@latest

# You'll see output like:
# Playwright MCP Server listening on stdio
# Press Ctrl+C to stop

If you see the "listening" message, the package works. Press Ctrl+C to stop it — your AI client will start it automatically.

Step 2A: Configure Claude Desktop

Claude Desktop is the GUI app for Mac, Windows, and Linux. This is the easiest way to get started with Playwright MCP Server.

1

Open the Claude Desktop config file

Go to Claude Desktop → Settings → Developer → Edit Config. This opens your claude_desktop_config.json file. If it doesn't exist yet, Claude will create it.

Config file locations by platform:

Config file paths
# macOS
~/Library/Application Support/Claude/claude_desktop_config.json

# Windows
%APPDATA%\Claude\claude_desktop_config.json

# Linux
~/.config/Claude/claude_desktop_config.json
2

Add the Playwright MCP Server entry

Paste this JSON into your config. If the file already has content, merge the mcpServers object with any existing entries.

claude_desktop_config.json — minimal setup
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    }
  }
}
3

Restart Claude Desktop

Fully quit Claude Desktop (not just close the window) and reopen it. Look for the hammer/tools icon in the chat input area — click it and you should see Playwright listed as a connected tool.

Windows users: If Claude can't find npx, use the full path: "command": "C:\\Program Files\\nodejs\\npx.cmd". This is the most common Windows setup issue.

Step 2B: Configure Claude Code (CLI)

Claude Code is the terminal-based Claude client — recommended for developers. You can configure MCP servers at the project level or globally.

Option A: Project-level config (recommended)

This keeps the MCP config scoped to your Playwright project and lets your team share it through git. Run this from your project root:

Terminal
claude mcp add --scope project playwright npx @playwright/mcp@latest

It writes a .mcp.json file in your project root. You can also create the file by hand:

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

Option B: Global config

If you want Playwright MCP available in every Claude Code session, add it at user scope. Claude Code saves it in ~/.claude.json:

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

Not .claude/settings.json: Claude Code doesn't load MCP servers from its settings files. Use claude mcp add or .mcp.json.

Start a new Claude Code session (claude in your terminal). Type /mcp to verify Playwright appears as a connected server.

Step 2C: Configure VS Code

If you use the Claude extension for VS Code, you can configure MCP servers directly in the extension settings:

1

Open VS Code settings

Press Cmd+Shift+P (Mac) or Ctrl+Shift+P (Windows/Linux), type "Claude: Settings", and open the Claude extension settings.

2

Add MCP server configuration

Find the MCP Servers section and add a new entry with the same JSON structure used for Claude Desktop.

3

Reload the extension

Run "Developer: Reload Window" from the command palette. Playwright will appear as an available tool in the Claude sidebar.

Alternatively, add the config directly to your workspace .vscode/settings.json:

.vscode/settings.json
{
  "claude.mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    }
  }
}

Step 3: Verify Your Setup Works

Run this quick smoke test in any Claude client. Type:

Prompt to Claude
Navigate to https://playwright.dev and take a snapshot.
Tell me what the page title is and list the main navigation links.

If everything is configured correctly, Claude will:

  1. Launch a browser via the MCP server
  2. Navigate to the Playwright docs site
  3. Return the page's accessibility tree with the title and navigation elements

If this works, your setup is complete. You're ready to start generating tests with Claude + MCP.

Advanced Configuration Options

The basic setup works for most people, but Playwright MCP Server has several flags that unlock more powerful workflows.

Headed vs headless mode

By default, Playwright MCP is headed: a browser window opens so you can watch Claude interact with your app in real time. Add --headless to run without a window:

claude_desktop_config.json — headless mode
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest", "--headless"]
    }
  }
}

When to use each: keep the default headed mode for demos, debugging MCP issues and learning how Claude interacts with pages. Use --headless on CI servers or when you don't want a window stealing focus.

Browser selection

MCP defaults to Chromium. You can switch to Firefox or WebKit:

Firefox or WebKit
# Firefox
"args": ["@playwright/mcp@latest", "--browser", "firefox"]

# WebKit (Safari engine)
"args": ["@playwright/mcp@latest", "--browser", "webkit"]

Custom viewport size

Set a specific viewport to test responsive layouts or mobile views:

Custom viewport
"args": ["@playwright/mcp@latest", "--viewport-size", "375,812"]

Saved authentication state

Testing pages behind login is one of the biggest challenges with AI-driven testing. Playwright MCP Server solves this with saved auth state:

1

Log in manually once and save the state

Use Playwright's storageState to capture cookies, localStorage, and session tokens after logging in.

TypeScript — save auth state
import { chromium } from 'playwright';

const browser = await chromium.launch({ headless: false });
const context = await browser.newContext();
const page = await context.newPage();

// Navigate and log in manually in the browser window
await page.goto('https://your-app.com/login');
await page.pause(); // Browser stays open — log in manually

// After logging in, save the state
await context.storageState({ path: './auth/state.json' });
await browser.close();
2

Point MCP Server to the saved auth state

Add the --isolated and --storage-state flags to your config. Each session then starts in a fresh browser context that is already logged in.

Config with auth state
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--isolated",
        "--storage-state",
        "./auth/state.json"
      ]
    }
  }
}

Security: Add your auth/ directory to .gitignore. It contains session tokens that should never be committed to version control.

Complete flags reference

Flag Default Description
--headless off (headed) Run the browser without a window. By default you see it while Claude navigates
--browser chrome Browser or Chrome channel: chrome, firefox, webkit or msedge
--viewport-size browser default Viewport size in pixels, for example 1280x720
--storage-state none Path to a saved storageState file for isolated sessions (use with --isolated)
--isolated off Keep the browser profile in memory instead of saving it to disk
--port stdio Listen on a port (HTTP/SSE transport) instead of stdio
--host localhost Host to bind when using --port

Environment Variables & Proxy

If your application runs behind a corporate proxy or needs specific environment variables, pass them through the MCP config:

Config with proxy and env vars
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"],
      "env": {
        "HTTP_PROXY": "http://proxy.company.com:8080",
        "HTTPS_PROXY": "http://proxy.company.com:8080",
        "NO_PROXY": "localhost,127.0.0.1",
        "BASE_URL": "http://localhost:3000"
      }
    }
  }
}

Troubleshooting: 10 Common Setup Issues

If your setup isn't working, find your error below. These cover 95% of Playwright MCP Server setup problems reported in 2026.

1. "npx: command not found"

Cause: Node.js isn't installed or isn't on your PATH.
Fix: Install Node.js 18+ from nodejs.org. On Windows, use the MSI installer which adds Node to PATH automatically. On Mac, use brew install node.

2. "Cannot find module @playwright/mcp"

Cause: The package doesn't exist in the npx cache and the network request failed.
Fix: Run npx @playwright/mcp@latest manually in your terminal first. If you're behind a firewall, check your proxy settings or install globally: npm install -g @playwright/mcp.

3. Claude Desktop shows no tools / Playwright not listed

Cause: Config file has a JSON syntax error, or Claude wasn't fully restarted.
Fix: Validate your JSON at jsonlint.com. Then fully quit Claude Desktop (Cmd+Q on Mac, not just close window) and reopen it.

4. "Browser closed unexpectedly" or "Browser executable not found"

Cause: Playwright browsers aren't installed.
Fix: Run npx playwright install to download Chromium, Firefox, and WebKit. For just Chromium: npx playwright install chromium.

Terminal
# Install all browsers
npx playwright install

# Install Chromium only (faster)
npx playwright install chromium

# Install with system dependencies (Linux)
npx playwright install --with-deps

5. Windows: "spawn npx ENOENT"

Cause: Claude can't find npx on Windows because it's not in the system PATH for the Claude process.
Fix: Use the full path to npx:

Windows fix
{
  "mcpServers": {
    "playwright": {
      "command": "C:\\Program Files\\nodejs\\npx.cmd",
      "args": ["@playwright/mcp@latest"]
    }
  }
}

6. "Connection refused" when navigating to localhost

Cause: Your dev server isn't running, or it's on a different port than what you told Claude.
Fix: Start your dev server first (npm run dev), then ask Claude to navigate. Verify the port matches.

7. MCP Server starts but Claude says "tool call failed"

Cause: Usually a version mismatch or the MCP Server crashed mid-session.
Fix: Update to the latest version: npx @playwright/mcp@latest. If you installed globally, run npm update -g @playwright/mcp. Restart Claude.

8. Pages behind login return "redirected to /login"

Cause: No saved authentication state — Claude starts a fresh browser session each time.
Fix: Use the saved auth state approach described above. Save your login cookies once, then point MCP to the auth directory.

9. Linux: "No usable sandbox"

Cause: Chromium needs a sandbox and the user namespace isn't configured.
Fix: Install system dependencies: npx playwright install --with-deps. If running in Docker, add --no-sandbox to the browser launch args or use the official Playwright Docker image.

10. Slow startup (~15+ seconds)

Cause: npx downloads the package fresh each time if your npm cache is cold.
Fix: Install globally (npm install -g @playwright/mcp) and change your config to use the global binary:

Global install config
{
  "mcpServers": {
    "playwright": {
      "command": "playwright-mcp",
      "args": []
    }
  }
}

Platform-Specific Configs (Copy & Paste)

Here are ready-to-use configs for the three most common setups:

macOS + Claude Desktop + Headless Mode

~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest", "--headless"]
    }
  }
}

Windows + Claude Desktop + Full Path

%APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "playwright": {
      "command": "C:\\Program Files\\nodejs\\npx.cmd",
      "args": ["@playwright/mcp@latest"]
    }
  }
}

Linux + Claude Code + Auth State + Firefox

.mcp.json
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--browser", "firefox",
        "--isolated", "--storage-state", "./auth/state.json"
      ],
      "env": {}
    }
  }
}

MCP Server vs Playwright Codegen: When to Use Which

Both tools generate test code, but they work differently. Use the right tool for the right job:

Playwright MCP Server Playwright Codegen
How it works AI reads the page and writes tests from descriptions Records your manual clicks and generates code
Input Plain English prompt Manual browser interaction
Selector quality Role-based (getByRole, getByLabel) — highly resilient Mixed — often falls back to CSS/XPath
Test structure Full tests with assertions, edge cases, and POM support Linear recording — no assertions by default
Best for Generating entire test suites, debugging, self-healing Quick recordings, learning selectors, simple flows
Requires Claude subscription or API key Nothing — built into Playwright

For a deep dive into Codegen, see our Playwright Codegen tutorial. For most teams in 2026, MCP + Claude is the primary workflow and Codegen is a quick supplementary tool.

What to Do After Setup

Now that your Playwright MCP Server is running, here's your learning path:

  1. Generate your first test — follow our MCP + Claude test generation guide
  2. Connect MCP to Playwright Agents — run npx playwright init-agents --loop=claude to add the planner, generator and healer agent definitions that Claude Code can use alongside the MCP Server. See the Playwright Test Agents guide for the full setup.
  3. Learn self-healing locators — see self-healing locators with AI
  4. Set up CI/CD with Docker — the MCP Server is for interactive work with Claude; in CI you run the tests it helped you write, headlessly, in the official Playwright Docker image:
GitHub Actions — Playwright tests in Docker
# .github/workflows/playwright-mcp.yml
name: Playwright Tests
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    container:
      image: mcr.microsoft.com/playwright:v1.56.0-noble
    steps:
      - uses: actions/checkout@v4
      - name: Install dependencies
        run: npm ci
      - name: Run Playwright tests
        run: npx playwright test
  1. Master the full workflow — the Playwright + Claude AI course covers everything end to end

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 →

Next step: once the server is running, see which tools Claude can call and how to enable the opt-in groups in the Playwright MCP tools reference.

Frequently Asked Questions

How do I install Playwright MCP Server?

Run npx @playwright/mcp@latest — no separate install needed. For faster startup, install globally with npm install -g @playwright/mcp. Then add the server to your Claude Desktop, Claude Code, or VS Code MCP settings.

Does Playwright MCP Server work on Windows, Mac, and Linux?

Yes. It works on all three platforms. On Windows, you may need to use the full path to npx (C:\Program Files\nodejs\npx.cmd) in your config if Claude can't find it on the PATH.

Can I use Playwright MCP Server with VS Code?

Yes. Configure it in the Claude VS Code extension settings or via Claude Code in VS Code's integrated terminal. Both approaches give Claude full browser access through the MCP Server.

Why is Playwright MCP Server not connecting?

The most common causes: Node.js not installed or below v18, npx not on your system PATH, a JSON syntax error in your config, or not fully restarting Claude after editing the config. Test the server manually first: npx @playwright/mcp@latest.

Can Playwright MCP Server test pages behind login?

Yes. Log in manually once and save the state with storageState, then start the MCP Server with --isolated --storage-state ./auth/state.json. Each session reuses those cookies and tokens.

What is the difference between Playwright MCP Server and Playwright Codegen?

Codegen records your manual browser interactions and generates code from them. MCP Server gives Claude direct browser access so it autonomously navigates, inspects, and generates tests from plain English — no manual recording needed. MCP also supports debugging, self-healing, and POM generation.

How do I use Playwright MCP Server with Playwright Test Agents?

Run npx playwright init-agents --loop=claude. It adds planner, generator and healer agent definitions to your project that Claude Code can use. The MCP Server stays useful alongside them: it gives Claude a live browser for exploring and debugging outside the plan, generate and heal workflow.

Can Playwright MCP Server run in Docker for CI/CD?

Yes, but in CI you usually run the tests rather than the MCP Server. Use the official mcr.microsoft.com/playwright Docker image and run npx playwright test. If you want AI fixes in CI, run Claude Code headless in a separate job and have it open a pull request, so a person reviews every change.

What is the difference between Playwright MCP and Claude in Chrome?

Playwright MCP runs a controlled Playwright browser that Claude interacts with via structured tool calls — ideal for test generation and CI. Claude in Chrome uses a browser extension to give Claude access to your existing Chrome session — better for one-off debugging and accessibility checks. See the full MCP vs Claude in Chrome comparison.

How do I update Playwright MCP Server to the latest version?

Run npm install -g @playwright/mcp@latest to update the global install, or npx @playwright/mcp@latest always uses the latest version without a global install. Check the current version with npx @playwright/mcp --version. Update your Playwright test package separately with npm install @playwright/test@latest — the two packages version independently.

Does Playwright MCP Server work with Cursor and Windsurf?

Yes. Any MCP-compatible client works with the Playwright MCP Server. In Cursor, add the server to .cursor/mcp.json in your project (or the global ~/.cursor/mcp.json). In Windsurf, add it to ~/.codeium/windsurf/mcp_config.json. The entry is the same as Claude Code's .mcp.json: the same command and args; only the file location differs.


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 →