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:
- Node.js 18+ — run
node --versionto check. If you're below 18, download the LTS version. - A Playwright project — if you don't have one yet:
npm init playwright@latest. See our Playwright for beginners guide for a walkthrough. - 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 ✓
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:
# 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.
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:
# macOS ~/Library/Application Support/Claude/claude_desktop_config.json # Windows %APPDATA%\Claude\claude_desktop_config.json # Linux ~/.config/Claude/claude_desktop_config.json
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.
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": ["@playwright/mcp@latest"]
}
}
}
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:
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:
{
"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:
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:
Open VS Code settings
Press Cmd+Shift+P (Mac) or Ctrl+Shift+P (Windows/Linux), type "Claude: Settings", and open the Claude extension settings.
Add MCP server configuration
Find the MCP Servers section and add a new entry with the same JSON structure used for Claude Desktop.
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:
{
"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:
- Launch a browser via the MCP server
- Navigate to the Playwright docs site
- 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:
{
"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 "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:
Log in manually once and save the state
Use Playwright's storageState to capture cookies, localStorage, and session tokens after logging in.
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();
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.
{
"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:
{
"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 + Headless Mode
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": ["@playwright/mcp@latest", "--headless"]
}
}
}
Windows + Claude Desktop + Full Path
{
"mcpServers": {
"playwright": {
"command": "C:\\Program Files\\nodejs\\npx.cmd",
"args": ["@playwright/mcp@latest"]
}
}
}
Linux + Claude Code + Auth State + Firefox
{
"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:
- Generate your first test — follow our MCP + Claude test generation guide
- Connect MCP to Playwright Agents — run
npx playwright init-agents --loop=claudeto 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. - Learn self-healing locators — see self-healing locators with AI
- 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/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
- Master the full workflow — the Playwright + Claude AI course covers everything end to end
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
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