How to Add Playwright MCP Server to Claude Code (2026 Guide)

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. 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.

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.

# 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  ✓

Step 1: Install Playwright MCP Server

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

To verify the package is accessible, run it directly:

# 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.

Config file locations by platform:

# macOS
~/Library/Application Support/Claude/claude_desktop_config.json

# Windows
%APPDATA%\Claude\claude_desktop_config.json

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

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

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. Create or edit .claude/settings.json in your project root:

{
  "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 to your global settings:

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

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:

Alternatively, add the config directly to your workspace .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:

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 mode (see the browser)

By default, MCP runs headless — no visible browser window. Add --headed to watch Claude interact with your app in real time:

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

Browser selection

MCP defaults to Chromium. You can switch to 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:

"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:

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();

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--saved-auth-dir",
        "./auth"
      ]
    }
  }
}

Complete flags reference

Environment Variables & Proxy

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

{
  "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.

# 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:

{
  "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:

{
  "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 + Headed Mode

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

Windows + Claude Desktop + Full Path

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

Linux + Claude Code + Auth State + Firefox

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--browser", "firefox",
        "--saved-auth-dir", "./auth"
      ],
      "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:

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 scaffold the tri-agent pipeline (planner, generator, healer) with MCP as the browser interface. 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 — run MCP-powered tests headlessly in CI using the official Playwright Docker image:

# .github/workflows/playwright-mcp.yml
name: Playwright MCP 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 (heal mode)
        run: npx playwright test --agent heal
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

5. Master the full workflow — the Playwright + Claude AI course covers everything end to end

Frequently Asked Questions

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