Playwright MCP + Cursor: Complete Setup and Testing Workflow

Playwright MCP + Cursor setup is three steps: add @playwright/mcp to .cursor/mcp.json, enable MCP in Cursor’s settings, and verify the connection in Agent mode. Once it is connected, Cursor’s agent drives a real browser, reads the page as an accessibility tree, and writes test code against what the DOM actually contains. If you use Claude Code instead of Cursor, see our Claude Code setup guide. The MCP server is the same; only the registration step differs. This guide covers the Cursor-specific workflow end to end, including what to do with results after the test runs.

What Is Playwright MCP?

Playwright MCP is an official Model Context Protocol server, published by Microsoft as @playwright/mcp, that exposes a real browser as a set of tools an AI agent can call. The tools cover the full interaction surface: browser_navigate, browser_click, browser_fill, browser_snapshot (accessibility tree), browser_screenshot, and around two dozen others. The agent calls them in sequence, reads the results, and decides what to do next.

Does Playwright support MCP?

Yes. Microsoft publishes @playwright/mcp as an official package and maintains it alongside the Playwright project. It supports Chromium, Firefox, and WebKit. The same browser binaries the Playwright CLI uses are shared by the MCP server, so if you already run npx playwright test locally, the browsers are already installed.

Playwright MCP vs. Playwright CLI: which do you need in Cursor?

You need both, for different purposes.

The CLI is your persistent suite. The MCP is how Cursor’s agent explores the app, generates the spec, and validates a fix before you commit. If you are new to what the CLI produces, the Playwright reports guide covers each output format and when to use which.

Prerequisites

You need Node.js 18 or newer, an active Cursor subscription with Agent mode, and the Playwright browser binaries. Install the binaries with npx playwright install chromium if you have not already.

Cursor version requirements

MCP support requires Cursor 0.40 or newer. Check under Cursor > About or run cursor --version in a terminal. Older builds do not expose the mcp.json configuration path and the Features > MCP toggle does not appear in settings.

Node.js and npx setup

@playwright/mcp requires Node 18+. Confirm with node -v. The package runs via npx with no global install required, so your npx must be on PATH. If npx --version fails, reinstall Node.js from nodejs.org.

How to Use Playwright MCP in Cursor?

To use Playwright MCP in Cursor, add the server config to .cursor/mcp.json, enable MCP in settings, and verify the connection in Agent mode. The full flow takes under five minutes.

Install the Playwright MCP server

No global install is needed. Cursor launches the server with npx on demand. You do need the browser binaries:

npx playwright install chromium

Add --with-deps on Linux to pull in the system libraries Chromium needs:

npx playwright install --with-deps chromium

Add to .cursor/mcp.json (full example)

Create or edit .cursor/mcp.json in your project root (or your home directory for a global config). A minimal working config looks like this:

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

To pin a specific version instead of tracking @latest:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/[email protected]"]
    }
  }
}

To run headed (browser window visible) and target Firefox instead of Chromium:

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

Cursor reads .cursor/mcp.json from the project root first, then falls back to ~/.cursor/mcp.json. Project-level configs are useful for team repos where everyone needs the same server; global configs are useful for personal preferences like always running headed.

How to Enable MCP in Cursor?

Open Cursor Settings with Cmd+, (macOS) or Ctrl+, (Windows/Linux), navigate to Features > MCP, and toggle MCP on. After saving, restart Cursor. On the next launch, Cursor reads mcp.json and attempts to connect to each listed server.

You can also enable it per-project by dropping a .cursor/mcp.json in the repo: Cursor detects the file and activates the server for that workspace without requiring the global toggle.

Verify the connection (first interaction)

Open a new chat in Agent mode (not Ask or Edit mode; those do not execute MCP tools). Type:

Navigate to https://example.com and describe what's on the page.

Cursor calls browser_navigate, then browser_snapshot, and reports what the accessibility tree contains. If it works, you will see the tool calls in the chat and a description of the page. If the server fails to start, check the MCP panel in settings for an error message. Missing browser binaries are the most common cause.

What’s a Benefit of Using MCP with Playwright in Cursor?

The core benefit is that Cursor’s agent reads your actual DOM state instead of guessing. browser_snapshot returns the live accessibility tree: real roles, real labels, the current state of every input and button. The agent writes locators against that data, not against a static screenshot or a spec file written by hand weeks ago.

AI writes tests from live DOM state, not guesses

When Cursor’s agent calls browser_snapshot, it gets back structured text: every interactive element labeled with its role and accessible name. It writes a locator like getByRole('button', { name: 'Submit' }) because that is exactly what the snapshot contains, not because it inferred it from a screenshot or guessed from the HTML. The generated locator is resilient to layout changes because it targets semantics, not coordinates.

Instant test run and fix loop in the editor

After generating a spec, Cursor can run it immediately using the Playwright CLI, read the failure output, and propose a fix, all without leaving the editor. The loop: generate, run, read output, fix, run again. Compare this to the typical cycle of writing a test manually, pushing to CI, waiting for a run, reading the log, and iterating. The MCP collapses that cycle to seconds for the generate-and-validate step.

Screenshot-driven debugging

When a test fails, call browser_screenshot before closing the browser. The agent captures the page state at the moment of failure and can reason about what the DOM looks like versus what the test expected. This is the same information a human gets from Playwright’s trace viewer, surfaced in the editor without switching tools.

Running and Fixing Tests with Cursor AI + Playwright MCP

Generating a test from a live page

Start Agent mode and point it at a URL you want covered:

Navigate to http://localhost:3000/login and write a Playwright test in tests/login.spec.ts
that verifies a user can log in with valid credentials and sees the dashboard.

The agent navigates, snapshots the page, identifies the form inputs by their accessible names, and writes a test using those locators. Review what it produced before committing: check that the locators are role-based rather than CSS-path-based, and that the assertions match the real page behavior.

Running the test inside Cursor

Ask the agent to run the file:

Run tests/login.spec.ts with npx playwright test and show me the output.

Cursor runs the command in a terminal panel, captures stdout and stderr, and reads the result. If it passes, you are done. If it fails, the agent reads the error and proposes a fix without you copying the output manually.

Auto-healing a broken locator

When a deploy changes a label or restructures a component, the existing locator breaks. Give the agent the failing test and the live URL:

tests/login.spec.ts is failing with "unable to find role 'button' with name 'Log in'".
Navigate to http://localhost:3000/login and fix the locator.

The agent snapshots the page, finds the current label on the submit button (“Sign in”, “Continue”, whatever it changed to), updates the locator, and re-runs. No trace viewer, no manual inspection of the diff.

Connecting results to Gaffer for CI-level tracking

Running a test in Cursor is useful for the generate-and-validate step, but the results vanish when the session ends. To give those results history, pipe the output through Gaffer after each run.

In Gaffer’s own pipeline, after Cursor generates and runs a Playwright test via MCP, the result files are uploaded to the dashboard using gaffer upload ./test-results — each run lands in the history and is tracked automatically. The practical effect: after two weeks of Cursor-generated tests running against the dashboard suite, every result is queryable, flaky tests surface with their flip rates, and the pass rate trend is visible across the full window rather than just the last run.

In CI, use the gaffer-sh/gaffer-uploader@v2 Action after your test step:

- name: Run Playwright tests
  run: npx playwright test --reporter=line,junit

- name: Upload results to Gaffer
  if: always()
  uses: gaffer-sh/gaffer-uploader@v2
  with:
    gaffer_upload_token: ${{ secrets.GAFFER_PROJECT_TOKEN }}
    report_path: ./test-results
    commit_sha: ${{ github.sha }}
    branch: ${{ github.ref_name }}
    test_framework: playwright

if: always() is required. The runs you most need to keep are the failing ones; gating upload on success discards exactly what you want to investigate next. The full tracking setup is in Gaffer’s MCP docs and the broader CI angle is covered in share Playwright test reports.

Configuration Reference for Cursor

Headed vs. headless mode

Headless is the default. Add --headed to the args array to open a visible browser window:

"args": ["@playwright/mcp@latest", "--headed"]

Use headed mode locally when you want to watch the agent navigate. Use headless in CI: headed mode requires a display, and most CI runners do not have one.

Browser selection

Chromium is the default. Pass --browser to switch:

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

Valid values: chromium, firefox, webkit. Use the same browser as your target user base for realistic results. For CI cross-browser coverage, run separate jobs with separate configs rather than trying to parameterize a single MCP server.

Network monitoring setup

To intercept and log network requests, add --save-har with a path:

"args": ["@playwright/mcp@latest", "--save-har", "/tmp/network.har"]

The HAR file captures all requests made during the session. Useful for debugging auth flows, API calls the app makes behind the scenes, or confirming that a third-party service is being called correctly.

Troubleshooting Playwright MCP in Cursor

MCP server not connecting

Open Cursor Settings > Features > MCP and check the server status. A red indicator usually means the npx command failed. Common causes: node is not on the PATH Cursor uses (check with which node in a terminal opened from within Cursor), the @playwright/mcp package failed to download, or the mcp.json JSON is malformed. Validate the JSON with cat .cursor/mcp.json | node -e "process.stdin.resume(); let d=''; process.stdin.on('data',c=>d+=c); process.stdin.on('end',()=>{JSON.parse(d); console.log('valid');})".

Browser not launching

If the MCP server connects but browser_navigate fails, the browser binaries are missing. Run:

npx playwright install chromium

On Linux, add --with-deps. The MCP server and the Playwright CLI share the same browser cache at ~/.cache/ms-playwright, so this only needs to run once per machine.

Permission errors on macOS

macOS Gatekeeper may quarantine the Chromium binary downloaded by Playwright. If you see "Chromium" is damaged and can't be opened, run:

xattr -dr com.apple.quarantine ~/.cache/ms-playwright

This removes the quarantine attribute from the cache directory and all its contents. You may need to run it again after each npx playwright install if Gatekeeper re-applies the flag.

FAQs

Does Playwright support MCP?

Yes. Microsoft publishes an official Playwright MCP server as the @playwright/mcp npm package. It exposes a real Chromium, Firefox, or WebKit browser as MCP tools an AI agent can call: navigate, click, fill forms, snapshot the accessibility tree, and capture screenshots.

How to use Playwright MCP on Cursor?

Add an entry to .cursor/mcp.json pointing to @playwright/mcp via npx, then enable MCP in Cursor’s settings under Features > MCP. Once enabled, Cursor’s Agent mode can call the browser tools directly: ask it to navigate a URL, click an element, or write a test from the live page.

What’s a benefit of using MCP with Playwright in Cursor?

The AI reads your actual DOM state rather than guessing at selectors. Cursor’s agent calls browser_snapshot, gets back the real accessibility tree, and writes locators against what the page actually contains, not a static snapshot or a screenshot it has to OCR.

How do I enable MCP on my Cursor?

Open Cursor Settings (Cmd+, on macOS, Ctrl+, on Windows/Linux), go to Features > MCP, and toggle MCP on. Then add your server config to .cursor/mcp.json. Cursor picks up the file on restart and connects to any servers listed there.

The setup itself is quick. The part that accumulates over time is keeping the results: once Cursor-generated tests run in CI and upload to Gaffer, every subsequent session has history to reason against. Flaky tests surface with flip rates; regressions appear against a trend line rather than looking like fresh failures. The Playwright reports guide covers output formats if you are new to what the Playwright CLI produces, and the Gaffer MCP reference covers what the agent can query once results are stored.