How to use Playwright MCP: Complete setup guide

Playwright MCP hands an AI agent a real browser. Through Microsoft's @playwright/mcp server, Claude, Cursor, VS Code, Windsurf, or any other MCP client can open a URL, read the page, click links, fill forms, and check the result in Chromium, Firefox, WebKit, or Edge. The whole Playwright MCP setup is one JSON block in your client's config file; the browser downloads itself the first time an agent uses it.

Playwright MCP is more reliable than screenshot-driven automation because of what the model reads. Playwright MCP returns the page's accessibility tree, the same structure screen readers use, so every button, link, and input arrives as a labeled element with a stable ref the agent can act on directly. No coordinate guessing, no vision model, and roughly 200–400 tokens per snapshot instead of the thousands a screenshot or a raw DOM dump burns.

Worth settling before you install: if you only want browser automation inside a coding agent, the Playwright team now points to the Playwright CLI exposed as Agent Skills. CLI calls stay cheaper in context because they skip the large tool schemas and verbose accessibility trees that an MCP connection loads. That matters when the agent is also holding a codebase and a test suite in mind. MCP still fits agentic loops that need persistent state and repeated reasoning over page structure: exploratory automation, self-healing tests, and long-running autonomous workflows.

The sections below cover client-by-client configuration, the flags worth knowing (headless, isolated sessions, saved auth state, proxies, Docker), the tools you will actually call out of the 40-plus the server exposes, plus working automation examples and the failure modes that show up once the setup leaves your laptop.

What is Playwright MCP?

Playwright MCP is a Model Context Protocol server that hands an AI assistant a real browser. Once the Playwright MCP setup is done, Claude Code, Claude Desktop, Cursor, VS Code, Windsurf, or any other MCP client can drive Chromium, Firefox, WebKit, or Edge: open a URL, click links and buttons, fill and submit forms, read page state, and run multi-step flows such as logging in, navigating, and verifying the result.

What makes it reliable is how the page gets described to the model. Playwright MCP returns the page's accessibility tree: every heading, link, button, and input as a labeled element with its own reference, like e5. The model acts on those references, so there is no vision model, no screenshot, and no coordinate guessing. A CSS tweak, a shifted element, or a different viewport size doesn't break the run the way pixel-based automation does. Snapshots are also cheap, in the region of 200–400 tokens each, against thousands for a screenshot or a raw DOM dump.

The interaction loop

When you say "click the login button," the work splits between your MCP client and the server:

1. Your client turns the request into a structured tool call against the tools the MCP server advertises.
2. The server translates that call into Playwright API calls against a live browser.
3. The action returns an accessibility snapshot of the resulting page, not an image.
4. The model reads the new snapshot, picks the next element reference, and repeats.

Because every action hands back fresh page state, the assistant can notice a validation error, a redirect, or a modal that appeared and adjust on the next step instead of blindly continuing. The browser opens in headed mode by default, so you can watch the whole loop happen and see exactly where a flow went wrong.

The tools you get

The core set covers the actions you'd perform by hand:

• browser_navigate loads a URL.
• browser_snapshot captures the accessibility tree with element refs.
• browser_click and browser_type interact with those refs.
• browser_wait_for holds until a condition is met.
• browser_screenshot captures pixels for the cases where you genuinely need an image.
• browser_evaluate runs JavaScript in the page context.

Beyond those, the server ships 40+ tools spanning navigation, forms, network mocking, storage, tracing, and video capture. browser_evaluate deserves a second thought before you enable it: arbitrary JavaScript execution in the page widens the blast radius considerably if an agent goes off-script or reads a prompt injection on a page it visits.

When the Playwright CLI is the better fit

Microsoft now points coding agents at a different option. The @playwright/mcp package itself recommends the Playwright CLI exposed as Agent Skills for coding agents, because CLI invocations skip loading large tool schemas and verbose accessibility trees into the context window. Agents juggling a codebase, a test suite, and browser work in one limited context get more room to think with concise, purpose-built commands.

MCP stays the right choice for agentic loops that benefit from persistent state, rich introspection, and repeated reasoning over page structure: exploratory automation, self-healing tests, and long-running autonomous workflows where the browser session needs to stay alive between steps. If your use case is "generate a Playwright test from this page," weigh the CLI. If it's "keep a browser open and reason about it," stay with MCP.

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/[email protected]"]
}

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.