How to use Playwright MCP: Complete setup guide

Playwright MCP lets AI agents control web browsers through structured commands instead of fragile screenshot-based automation. It works by reading the browser's accessibility tree, the same structure screen readers use, giving AI models reliable and fast access to page elements.

In this guide, you'll learn how to set up Playwright MCP in VS Code, Claude Desktop, and other environments. We'll cover configuration options, core tools, real automation examples, and common pitfalls to avoid.

What is Playwright MCP?

Playwright MCP is a Model Context Protocol server that bridges AI assistants and browser automation. Instead of taking screenshots and guessing where to click, it exposes the browser's semantic structure to language models.

This approach solves the core problem with visual AI automation: brittleness. Screenshot-based tools break when CSS changes, when elements shift position, or when viewport sizes differ. Playwright MCP sidesteps these issues entirely.

When you send a command like "click the login button," here's what happens behind the scenes:

1. The AI parses your natural language request
2. It queries the MCP server for available browser tools
3. Commands get converted to structured JSON
4. The MCP server translates JSON into Playwright API calls
5. Results return as accessibility tree snapshots, not images

This cycle creates a self-correcting system where AI can adapt to unexpected states and handle dynamic content.

Prerequisites

Before installing Playwright MCP, you need:

• Node.js 18 or later (LTS version recommended)
• npm or npx for package management
• An MCP-compatible client like VS Code, Claude Desktop, Cursor, or Claude Code

Verify your Node.js installation:

node --version
npm --version

Both commands should return version numbers without errors.

How to Install Playwright MCP in VS Code

VS Code integration is the most common setup. You have two options: command line or manual configuration.

Method 1: CLI Installation

Open your terminal and run:

# For VS Code Stable
code --add-mcp '{"name":"playwright","command":"npx","args":["@playwright/mcp@latest"]}'

# For VS Code Insiders
code-insiders --add-mcp '{"name":"playwright","command":"npx","args":["@playwright/mcp@latest"]}'

This registers the Playwright MCP server with VS Code. GitHub Copilot's agent mode can then launch and communicate with it automatically.

Method 2: Manual Configuration

Edit your VS Code settings.json file directly. Open the command palette (Ctrl+Shift+P or Cmd+Shift+P), type "Open Settings JSON," and add:

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

Save the file and restart VS Code.

Verifying the Installation

Test your setup with a simple command:

1. Open GitHub Copilot chat
2. Switch to "Agent" mode
3. Type: "Use playwright mcp to navigate to google.com and take a screenshot"

A Chrome window should open, controlled by the AI. If you see the browser launch and navigate, your installation works.

How to Install Playwright MCP in Claude Desktop

Claude Desktop has native MCP support, making setup straightforward.

Step 1: Locate the Config File

Find your Claude Desktop configuration file:

• Windows: C:\Users\{username}\AppData\Roaming\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Step 2: Add the Server Configuration

Open the config file and add:

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

The -y flag automatically accepts prompts during package installation.

Step 3: Restart Claude Desktop

Completely close Claude Desktop. On Windows, check Task Manager to ensure no Claude processes are running. On macOS, use Activity Monitor.

Relaunch the application. Playwright MCP should now be available.

How to Install Playwright MCP in Claude Code

For terminal-based workflows, Claude Code offers a simple setup:

claude mcp add playwright npx @playwright/mcp@latest

This command persists in your ~/.claude.json file and applies to the current directory. The configuration includes MCPs and allowed commands specific to each project.

When you run claude in your terminal, type "use playwright mcp" followed by your instruction. Claude Code will launch a visible browser window that you can watch as it executes commands.

How to Install Playwright MCP in Cursor

Cursor has built-in MCP support. Here's how to configure it:

1. Open Cursor Settings
2. Navigate to Tools & MCP tab
3. Click Add Custom MCP
4. Paste the standard configuration:

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

Save and restart Cursor to apply the changes.

Configuration Options for Playwright MCP

Playwright MCP accepts command-line arguments that modify its behavior. Add these to the args array in your configuration.

Running in Headless Mode

For CI/CD pipelines or background execution:

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

Headless mode runs without a visible browser window, saving resources.

Choosing a Browser

Playwright MCP supports Chrome, Firefox, WebKit, and Microsoft Edge:

{
  "args": ["@playwright/mcp@latest", "--browser", "firefox"]
}

Chrome is the default. Firefox and WebKit provide cross-browser testing capabilities.

Setting Viewport Size

Control the browser window dimensions:

{
  "args": ["@playwright/mcp@latest", "--viewport-size", "1280x720"]
}

This ensures consistent rendering across different machines.

Enabling Vision Mode

By default, Playwright MCP uses Snapshot Mode, which reads the accessibility tree. Vision Mode captures screenshots instead:

{
  "args": ["@playwright/mcp@latest", "--caps", "vision"]
}

Vision Mode is useful when accessibility information is incomplete, like custom canvas elements or graphical interfaces.

Device Emulation

Test mobile layouts by emulating specific devices:

{
  "args": ["@playwright/mcp@latest", "--device", "iPhone 15"]
}

This applies the device's viewport, user agent, and touch capabilities.

Core Playwright MCP Tools

Once connected, your AI agent can invoke these browser automation tools:

Navigation Tools

• browser_navigate: Go to a URL
• browser_navigate_back: Return to previous page
• browser_snapshot: Capture the accessibility tree

Interaction Tools

• browser_click: Click an element by reference
• browser_type: Enter text into input fields
• browser_hover: Mouse over an element
• browser_select_option: Choose dropdown values
• browser_file_upload: Upload files to input elements

Page Tools

• browser_take_screenshot: Capture visual output
• browser_press_key: Simulate keyboard input
• browser_wait_for: Wait for conditions
• browser_close: Close the browser

Each tool in Snapshot Mode uses element references (ref) from the accessibility tree. The AI requests a snapshot, identifies the target element's reference, then passes that reference to interaction tools.

Practical Example: Automating a Login Flow

Here's how Playwright MCP handles a typical login automation:

First, the AI requests a snapshot of the page:

User: "Navigate to example.com/login and log in with username 'testuser' and password 'testpass123'"

The AI then:

1. Calls browser_navigate with the login URL
2. Calls browser_snapshot to get page structure
3. Identifies the username field's ref from the snapshot
4. Calls browser_type with the ref and "testuser"
5. Identifies the password field's ref
6. Calls browser_type with the ref and "testpass123"
7. Identifies the submit button's ref
8. Calls browser_click to submit the form
9. Calls browser_snapshot to verify the result

The AI handles element discovery automatically. You just describe the goal in plain language.

Common Issues and How to Fix Them

Browser Not Found Error

If you see errors about missing browsers, install them manually:

npx playwright install
npx playwright install-deps

The first command downloads browser binaries. The second installs system dependencies on Linux.

Connection Refused

This usually means the MCP server isn't running when the client tries to connect. Solutions:

• Restart your IDE completely
• Check for port conflicts if using SSE transport
• Verify the configuration syntax is valid JSON

Version Mismatch Errors

If you encounter module errors like "Cannot find module './lib/servers/snapshot'", pin to a specific version:

{
  "args": ["@playwright/mcp@0.0.40"]
}

The @latest tag sometimes pulls unstable releases.

WSL and Linux Display Issues

On Windows Subsystem for Linux without a display, you need either headless mode or a virtual framebuffer:

# Install xvfb for virtual display
sudo apt-get install xvfb

# Run with virtual display
xvfb-run npx @playwright/mcp@latest

Alternatively, use SSE transport with a standalone server process.

Using SSE Transport for Remote Access

When running Playwright MCP on a remote server or in environments without direct process access, use HTTP transport:

Start the Server with a Port

npx @playwright/mcp@latest --port 8931

Configure Your Client

{
  "mcpServers": {
    "playwright": {
      "url": "http://localhost:8931/mcp"
    }
  }
}

This setup separates the browser process from your IDE, useful for debugging and remote execution scenarios.

User Data and Persistent Sessions

Playwright MCP maintains browser profiles at these locations:

• Windows: %USERPROFILE%\AppData\Local\ms-playwright\mcp-chrome-profile
• macOS: ~/Library/Caches/ms-playwright/mcp-chrome-profile
• Linux: ~/.cache/ms-playwright/mcp-chrome-profile

Login sessions persist across MCP restarts. Delete these directories for a fresh browser state.

For isolated sessions that don't persist, add the --isolated flag:

{
  "args": ["@playwright/mcp@latest", "--isolated"]
}

Snapshot Mode vs Vision Mode

Playwright MCP operates in two modes with different trade-offs.

Snapshot Mode (default) reads the accessibility tree:

• Fast and lightweight
• Works best with semantic HTML
• Element references are deterministic
• No visual processing required

Vision Mode captures screenshots:

• Works with canvas and custom graphics
• Requires coordinate-based interactions
• Slower due to image processing
• Useful when accessibility markup is missing

Start with Snapshot Mode. Switch to Vision Mode only when you encounter elements invisible to the accessibility tree.

Security Considerations

Playwright MCP executes browser commands with your user permissions. Keep these points in mind:

• Avoid hardcoding credentials in prompts or configuration
• Review actions before confirmation in interactive sessions
• Use isolated mode for sensitive testing to prevent session leakage
• Restrict network access with --blocked-origins for untrusted sites

The MCP server can perform any action you could do manually in a browser. Treat it like giving someone else control of your mouse and keyboard.

Integration with Test Frameworks

Playwright MCP generates tests compatible with standard Playwright test syntax. A typical workflow:

1. Describe your test scenario in natural language
2. Let the AI explore the application and identify elements
3. Export generated code to your tests/ directory
4. Run tests with npx playwright test

The AI handles element discovery and generates maintainable locators. You focus on describing behavior, not writing selectors.

Final Thoughts

Playwright MCP changes how we approach browser automation. Instead of wrestling with selectors and timing issues, you describe what you want in plain language.

The accessibility tree approach eliminates the fragility of screenshot-based automation. Elements are identified by their semantic meaning, not their pixel position.

Start with VS Code or Claude Desktop for the smoothest experience. Use the default Snapshot Mode unless you have specific visual automation needs. And remember that the AI can adapt and recover from unexpected states, something traditional automation scripts can't do.

Ready to try it? Install Playwright MCP, open your favorite AI assistant in agent mode, and ask it to explore a website. Watch how it navigates, discovers elements, and responds to what it finds.