Setting up Playwright MCP takes about two minutes. The confusing part is that every AI client wants the config in a slightly different place. This guide gives you the exact commands for Claude, Cursor, and VS Code, then the handful of flags that actually matter once you go past the demo.

Prerequisites

Node.js 18 or newer. That is the only hard requirement.
A browser. Playwright MCP uses Playwright's browsers. The safe move is to pre-install one so the first run does not fail:

npx playwright install chromium

That is it. There is nothing else to install globally, because you run the server on demand with npx.

Step 1: the one config that works almost everywhere

Most MCP clients share the same JSON shape. This block is the canonical Playwright MCP config, and it works in Cursor, VS Code, Windsurf, Claude Desktop, and more:

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

The differences below are just where each client keeps that block.

Claude

For Claude Code (the CLI), you do not edit JSON at all. One command:

claude mcp add playwright npx @playwright/mcp@latest

Add -s user if you want it available across all your projects:

claude mcp add playwright -s user -- npx @playwright/mcp@latest

For Claude Desktop, drop the standard mcpServers block from Step 1 into its MCP config file (Claude's own docs list the exact path for your OS), then restart the app.

Cursor

Open Cursor Settings → MCP → Add new MCP Server. Choose command as the type and enter:

npx @playwright/mcp@latest

Cursor writes this into its own mcp.json using the same mcpServers shape as Step 1, so you can also paste the JSON block directly if you prefer.

VS Code

With GitHub Copilot's agent mode, install it in one line:

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

Verify it works

Start a fresh chat in your client and ask the agent to "open example.com and tell me the page title." If it calls browser_navigate and browser_snapshot and comes back with the title, you are done. A browser window will pop up, because Playwright MCP runs headed by default.

The flags that actually matter

You pass flags after the package name, for example npx @playwright/mcp@latest --headless --isolated. The ones worth knowing:

--headless – run with no visible window. You want this in CI and on servers.
--isolated – keep the browser profile in memory and throw it away on close. Combine with --storage-state=auth.json to start each session already logged in.
--browser chrome|firefox|webkit|msedge – pick the engine or channel.
--device "iPhone 15" – emulate a device (names track Playwright's device list).
--caps=vision – add coordinate-based mouse tools, for the rare case the accessibility tree is not enough. There is no --vision flag; it is a capability.
--user-data-dir <path> – use a specific persistent profile.

One gotcha: the default persistent profile is single-instance. If two clients point at the same workspace, they conflict. Give each extra client --isolated or its own --user-data-dir.

Running it in CI or on a headless host

For automation, the cleanest option is the official Docker image (headless Chromium):

{
  "mcpServers": {
    "playwright": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "--init", "--pull=always", "mcr.microsoft.com/playwright/mcp"]
    }
  }
}

On Linux you often need --no-sandbox. For a remote or long-lived setup, run the server over HTTP and point the client at the URL:

npx @playwright/mcp@latest --port 8931

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

Do not skip the security step

Microsoft is explicit that Playwright MCP is not a security boundary, and it includes a browser_run_code_unsafe tool that is effectively remote code execution. For interactive local use that is fine. The moment you run it unattended, isolate it: a container, --isolated, throwaway credentials, and no access to anything sensitive. Treat an MCP-driven browser like any other code your agent can run.

When you would want a managed alternative

The setup above is perfect for you, sitting at your machine, driving a browser through an agent. It gets harder when you want this running on a schedule, across environments, with traces and pass/fail history that a team can review, and without one cold npx spin-up per run.

That is the line where teams move from raw Playwright MCP to a managed platform. Test-Lab.ai runs the same kind of structured AI-agent testing, but hosted, with evidence capture, scheduling, and CI built in, and it is agent-native, so your own tools can trigger and read runs over MCP.

Want the agent-driven testing without running and babysitting MCP servers? Try Test-Lab free and run your first test in minutes.

Related reading:

What is Playwright MCP? – the concepts behind the config
Playwright MCP vs Playwright CLI – which approach fits your agent
Chrome DevTools MCP vs Playwright MCP vs CLI – the wider landscape
The best AI QA tools in 2026 – an honest, ranked comparison

How to Set Up Playwright MCP for Claude, Cursor, and VS Code