Playwright MCP Server Cursor IDE Setup 2026: Browser Automation From Chat

How do you set up the Playwright MCP server in Cursor? Add a playwright entry under mcpServers in ~/.cursor/mcp.json running npx @playwright/mcp@latest, restart Cursor, and confirm a green status. No API key, no account, nothing to authenticate — the server drives a local browser directly. Ask Cursor to open a URL and click something; if a real browser window responds, you're connected.

This page covers Microsoft's official @playwright/mcp package — the one maintained in the microsoft/playwright-mcp repository, not the older third-party executeautomation/mcp-playwright wrapper that predates it and uses a different tool surface. If you're following a tutorial from 2024, check the package name in the config before pasting it in; @playwright/mcp and the community wrapper are not interchangeable.

Why This Isn't Just "Screenshots for the AI"

The detail that matters most: Playwright MCP doesn't feed Cursor pixels. It uses Playwright's accessibility tree — the same structured representation screen readers consume — to describe a page as text: elements, roles, labels, and state. Cursor reasons over that structure instead of trying to interpret a PNG, which is why it can reliably click "the submit button in the second form" without a vision model guessing coordinates from an image. Screenshots are still available as an explicit tool call when you actually want visual verification, but they aren't the default interaction loop.

Quick Reference

Prerequisites

Step 1: Add the Server to Cursor's mcp.json

Open ~/.cursor/mcp.json for a global install (available in every project) or .cursor/mcp.json in a project root to scope it to one repo:

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

Restart Cursor completely — not just reload the window — for a new MCP entry to register. You can also add it through Cursor Settings → MCP → Add new MCP Server, using command type with npx @playwright/mcp@latest, which writes the same block into mcp.json for you.

Step 2: Configure Browser and Session Behavior

The default config launches Chrome, headed, with a persistent profile stored on disk — fine for interactive debugging, wrong for CI or for running two Cursor sessions against the browser at once. Pass flags as additional args entries:

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

--isolated is the one to reach for first if you ever see the profile-conflict error below — it sidesteps the whole class of problem rather than requiring you to close every other browser window first.

Step 3: Verify Installation

Playwright's browser binaries download automatically the first time a tool call needs them, but it's worth pre-installing so the first real request in Cursor isn't the moment you discover a slow download:

npx playwright install

This pulls Chromium, Firefox, and WebKit. If you only pass --browser chrome in your config, you can scope the install the same way: npx playwright install chromium.

Step 4: Test the Connection

In Cursor chat:

Open https://example.com and tell me what the page title and main heading say.

A browser window should open (unless you set --headless), navigate, and Cursor should respond with real page content rather than a generic answer. If nothing happens, check Output → MCP Logs (Cmd+Shift+U on macOS, Ctrl+Shift+U on Windows/Linux) before assuming the config is wrong.

Step 5: Practical Workflows

End-to-end debugging without writing a test file first

Go to my local app at localhost:3000, log in with test@example.com / testpass123, navigate to the billing page, and tell me if the "Upgrade Plan" button is actually clickable or disabled.

Generating a real Playwright test from an exploratory session

Walk through the signup flow on localhost:3000 step by step — enter test data at each field — then write a Playwright test in TypeScript that reproduces exactly what you just did, using the same selectors.

Visual regression spot-check

Open the pricing page, take a screenshot, then open the same page in a 375px-wide mobile viewport and take another screenshot. Tell me if the three-column layout breaks on mobile.

Scraping structured data for a one-off task

Go to this competitor's public pricing page and extract every plan name, price, and feature list into a JSON array.

Troubleshooting

"A persistent profile can only be used by one browser instance at a time"
You have another Playwright MCP session, or a Chrome window opened by an earlier run, still holding the default profile lock. Add --isolated to your config so each session gets its own in-memory profile instead of fighting over one on disk — this is the actual fix, not just closing windows and hoping.

Server starts but browsers never launch, or the first request hangs for a long time
The browser binaries weren't pre-installed and are downloading now. Run npx playwright install in a terminal once, outside of Cursor, so you can see the download progress instead of staring at a silent tool call.

"Node.js not found" or the server fails immediately
Confirm node --version returns 18 or later in the same shell environment Cursor launches from — a version manager like nvm that only loads in interactive shells can leave Cursor's non-interactive process pointed at a system Node that's too old or missing entirely.

Agent clicks the wrong element on a page with duplicate labels
The accessibility tree exposes roles and labels, not visual position — two buttons both labeled "Edit" on a table with many rows look identical to the model unless you give it a disambiguating detail ("the Edit button in the row for user jane@example.com," not just "the Edit button").

Headless mode works but you can't see what's happening
That's expected — headless mode has no visible window by design. Drop --headless from the config while debugging a flow interactively, and add it back for unattended runs.

Permission or sandbox errors on Linux CI runners
Playwright's browsers need certain system dependencies that aren't always present on minimal container images. Run npx playwright install --with-deps instead of the plain install command to pull the OS-level dependencies alongside the browser binaries.

When Not to Use This

Don't point Playwright MCP at a production account with real customer data during exploratory sessions — an agent that's slightly wrong about "this looks like a test account" is a bad failure mode when it's clicking real buttons in a real logged-in session. Use --isolated with a dedicated test account, not your own logged-in browser profile.

Frequently Asked Questions

Q: Is @playwright/mcp the same as executeautomation/mcp-playwright?
A: No — they're different projects with different tool names. @playwright/mcp is Microsoft's official package, built directly on the Playwright library and using the accessibility tree as its primary interface. The community executeautomation wrapper predates it and exposes a different, broader tool set. This guide covers the official package.

Q: Does this require a Playwright test file or project to already exist?
A: No. The MCP server drives a browser directly — you can use it against any URL with zero existing test infrastructure. Generating an actual .spec.ts test file from an exploratory session (Step 5) is one workflow, not a prerequisite.

Q: Can I run this against a site that requires login?
A: Yes — ask Cursor to fill in credentials and submit the login form the same way a human would, or pre-authenticate with --user-data-dir pointing at a profile that's already logged in. Avoid pasting real production credentials directly into chat; use a dedicated test account.

Q: Why does the agent describe elements instead of showing me a screenshot by default?
A: The default interaction loop uses Playwright's accessibility tree — a text description of the page's structure — because it's faster and more reliable for the model to reason over than pixels. Screenshots are still available as an explicit tool call when you specifically need visual verification, like the mobile layout check in Step 5.

Q: Does this work with Firefox and Safari, or only Chrome?
A: Chrome, Firefox, and WebKit (Safari's engine) are all supported via --browser, plus Microsoft Edge via --browser msedge. Chrome is the default if you don't set the flag.

Related Guides

Official docs cited