Playwright MCP Claude Code: Setup, Options and Prompts

Playwright MCP Claude Code setup: the exact claude mcp add command, headless and browser options, test prompts for your app and how it differs from Chrome.

Josh Pocock7 min read

Playwright MCP cover

AI Coding

Playwright MCP

Stride AI Academy

To use Playwright MCP with Claude Code, run claude mcp add playwright npx @playwright/mcp@latest in your terminal, start Claude Code and ask it to open a page. Playwright MCP is Microsoft's MCP server that lets Claude drive a real browser: open pages, click, type, fill forms and read the page. It reads pages through Playwright's accessibility tree, so Claude works from structured data instead of screenshots.

This guide covers the install command, the options worth knowing, prompts for testing a web app you built, how it differs from Claude Code's Chrome integration, permissions and fixes for common problems. Everything here was checked against the microsoft/playwright-mcp README, the Claude Code MCP docs, the permissions docs and the Chrome integration docs on November 18, 2026.

What Playwright MCP does

Playwright is Microsoft's browser automation library. The MCP server wraps it in tools Claude can call, such as browser_navigate, browser_click, browser_type, browser_fill_form, browser_snapshot and browser_take_screenshot. It also has tools for console messages, network requests, tabs and file uploads.

The README makes two points about how it works:

  • It uses Playwright's accessibility tree, not pixel-based input.
  • No vision model is needed. It operates on structured data.

The browser_snapshot tool describes itself as better than a screenshot, and the screenshot tool tells the agent to use snapshots for actions by default. In practice, Claude reads a text outline of the page, then clicks or types on the elements it finds there.

You need Node.js 20 or newer, because the server runs through npx.

Install it in Claude Code

The README gives this command for Claude Code:

Terminal
claude mcp add playwright npx @playwright/mcp@latest

That adds a local server named playwright at the default local scope, which means this project only. To use it in every project, add --scope user. The MCP setup guide explains the three scopes and where each one saves its config.

When you want to pass options to the server, use the -- separator. Anthropic's docs say it separates Claude Code's own options from the command that starts the server. Without it, Claude Code tries to read the server's flags as its own:

Terminal
claude mcp add playwright --scope user \
  -- npx @playwright/mcp@latest --headless --isolated

Then start Claude Code and type /mcp. You should see playwright listed as connected.

From install to a tested page

  1. 1Run claude mcp addIn your terminal
  2. 2Start your dev serverFor example localhost:3000
  3. 3Type /mcp to confirm
  4. 4Ask Claude to test a flow
  5. 5Claude reports what broke

Options worth knowing

These all come from the README's options table. Add them after @playwright/mcp@latest in the command above.

Option What it does
--headless Runs the browser without a window. Headed is the default.
--browser Picks the browser: chrome, firefox, webkit or msedge.
--isolated Keeps the browser profile in memory and doesn't save it to disk.
--user-data-dir Sets where the profile is stored.
--storage-state Loads a storage state file into an isolated session, for example a saved login.
--device Emulates a device, for example "iPhone 15".
--viewport-size Sets the viewport in pixels, for example "1280x720".
--caps Turns on extra tool groups: vision, pdf or devtools.
--allowed-origins A semicolon-separated list of trusted origins the browser can request. All are allowed by default.
--output-dir Where screenshots and other output files go.
--save-session Saves the Playwright MCP session into the output directory.
--extension Connects to a running Chrome or Edge instead of launching a new browser.

Persistent or isolated profile

By default the server uses a persistent profile, so anything you log in to stays logged in next time. The README lists where it lives:

  • Windows: %USERPROFILE%\AppData\Local\ms-playwright\mcp-{channel}-{workspace-hash}
  • macOS: ~/Library/Caches/ms-playwright/mcp-{channel}-{workspace-hash}
  • Linux: ~/.cache/ms-playwright/mcp-{channel}-{workspace-hash}

With --isolated, each session starts with a fresh profile and the storage is lost when the browser closes. Use isolated mode for repeatable tests, and pair it with --storage-state if your app needs a logged-in user.

Prompts for testing a web app you built

Start your dev server first, then give Claude a specific flow and a specific thing to check. Vague prompts like "test my app" get vague results.

Check a form:

Open localhost:3000/signup. Submit the form empty, then with an
invalid email, then with valid data. Tell me which error messages
appear and whether the success page loads.

Find console errors:

Go to localhost:3000/dashboard and list any console errors or
failed network requests on page load. Then find the code that
causes the first one and fix it.

Check mobile layout:

Restart the server with --device "iPhone 15", then ask:

Open the pricing page and check that the plan cards stack, the
buttons are tappable and nothing overflows the screen. Take a
screenshot of anything that looks wrong.

Reproduce a bug:

A client says the booking form double-submits. Open
localhost:3000/book, fill it in, click Submit twice quickly and
check the network requests. Then fix it and test again.

Ask Claude to fix and re-test in the same prompt. That closes the loop: it changes the code, reloads the page and confirms the result.

Playwright MCP vs Claude Code's Chrome integration

Claude Code also has a built-in Chrome integration, started with claude --chrome. They overlap, but they work differently.

Playwright MCP Chrome integration
Browser One Playwright launches: Chrome, Firefox, WebKit or Edge Your own Chrome, Edge or another Chromium browser
Logins Its own profile, or none with --isolated Shares your browser's login state
Setup claude mcp add and Node.js 20+ Claude in Chrome extension and --chrome
Headless Yes, with --headless No, it runs in a visible window
Requirements Node.js 20 or newer A direct Anthropic plan and /login. Not supported in WSL

Use Playwright MCP for testing your own app in a clean, repeatable browser, including Firefox and WebKit. Use the Chrome integration when the task needs sites you're already signed in to.

One more note from the README: for coding agents, Microsoft says the Playwright CLI with skills can be the better fit, because CLI calls are more token-efficient. MCP stays useful for longer browser loops where Claude needs to keep the page state and inspect it closely.

Permissions and safety

Every Playwright tool is an MCP tool, so Claude Code asks before using it unless you've allowed it. Permission rules for MCP tools use the mcp__<server>__<tool> format. This setting in .claude/settings.json allows every Playwright tool but blocks the one that runs arbitrary code:

JSON
{
  "permissions": {
    "allow": ["mcp__playwright__*"],
    "deny": ["mcp__playwright__browser_run_code_unsafe"]
  }
}

The README calls browser_run_code_unsafe "RCE-equivalent", which means it can run code as if it were on your machine. More on rule syntax in Claude Code permissions.

Keep these points from the README in mind:

  • Playwright MCP is not a security boundary.
  • --allowed-origins limits where the browser goes, but the README says it isn't a security boundary either.
  • A persistent profile keeps your logins, so anything Claude can reach in that browser, it can act on.

Anthropic's MCP docs add that servers which fetch outside content can expose you to prompt injection. A page Claude visits could include hidden instructions. For anything beyond your own localhost, use --isolated, keep real accounts out of the profile and review what Claude does.

Fix common problems

  • The server doesn't connect. Check node --version is 20 or newer, then type /mcp to see the status. If it times out on start, raise the startup timeout: MCP_TIMEOUT=10000 claude.
  • Your flags are ignored or rejected. Put them after -- and the package name, not before.
  • A second session can't open the browser. The README says a persistent profile can only be used by one browser instance at a time. Close the other session, or use --isolated.
  • Snapshots get cut off on big pages. MCP output is capped at 25,000 tokens by default. Raise it with MAX_MCP_OUTPUT_TOKENS=50000 before starting Claude Code.
  • You need it on a server or in CI. Use --headless. The README notes the Docker image only supports headless Chromium for now. For scripted runs, see headless mode.

If you're choosing what else to connect, our list of MCP servers worth setting up first puts Playwright second, after GitHub.

Learn to build with Claude Code

The Stride AI Coding course teaches Claude Code and Codex for building client tools, written for non-programmers, with weekly live calls to review your builds. Many of the free guides cover Claude Code setups, and the Claude Code community is where members compare theirs.

FAQ

How do I add Playwright MCP to Claude Code?

Run claude mcp add playwright npx @playwright/mcp@latest, then type /mcp inside Claude Code to confirm it's connected. To pass options such as --headless, put them after a -- separator and the package name.

Does Playwright MCP need screenshots or a vision model?

No. It reads pages through Playwright's accessibility tree, so Claude works from a structured outline of the page. Screenshots are available, and --caps vision turns on the vision tools, but snapshots are the default.

Can Playwright MCP run headless?

Yes. Add --headless to the server command. The browser is headed by default, which lets you watch what Claude does.

What's the difference between Playwright MCP and Claude in Chrome?

Playwright MCP launches its own browser, with its own profile or an isolated one, and supports Chrome, Firefox, WebKit and Edge. The Chrome integration drives your own browser and shares your logins. Use Playwright for clean, repeatable tests of your app.

Is Playwright MCP safe to use?

The README says it is not a security boundary, so treat it like giving Claude a browser. Use --isolated for untrusted sites, keep real accounts out of its profile and deny browser_run_code_unsafe in your permission rules.

Build it with us in Stride AI Academy

Four courses, weekly live calls and a community of people building and selling AI. Or start with 310+ free guides.

Keep reading

Free AI Coding guides