Playwright MCP Claude Code Setup: Step-by-Step Guide

The One-Line Install

To use Playwright MCP in Claude Code, run claude mcp add playwright npx @playwright/mcp@latest, start claude, and check that playwright shows as connected in /mcp. From then on, Claude can open a real browser, click, type, read pages and take screenshots through Microsoft's official Playwright MCP server.

That command comes straight from the Playwright MCP README. The rest of this guide covers the choices you will hit right after it works: which scope to install in, headed vs headless, persistent vs isolated profiles, extra capabilities, and what to do when the browser does not start.

What Playwright MCP Actually Does

Playwright MCP exposes browser automation as MCP tools such as browser_navigate, browser_click, browser_type, browser_fill_form, browser_snapshot and browser_take_screenshot. Instead of sending screenshots to the model, it returns an accessibility snapshot: a structured tree of the page's elements with references Claude can click or fill. That makes it fast, cheap compared to vision-based approaches, and deterministic about which element it acts on.

Typical uses in Claude Code:

• Checking that the feature you just built actually works in a browser.
• Reproducing a UI bug from a ticket, step by step.
• Exploring a site and then writing Playwright tests for it.
• Filling forms or extracting data from pages that need JavaScript.

Prerequisites

• Node.js 18 or newer (the README's stated requirement). Check with node --version.
• Claude Code installed and signed in.
• A browser Playwright can drive. Choose chrome, firefox, webkit or msedge with --browser.

Step 1: Add the Server

Quickest: local scope

claude mcp add playwright npx @playwright/mcp@latest

This saves the server to the default local scope, so it is available only to you in the current project.

Available in every project: user scope

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

When you pass options to Playwright MCP itself, always put the launch command after --, so Claude Code does not try to read flags like --headless as its own.

Shared with your team: project scope

claude mcp add --scope project playwright -- npx @playwright/mcp@latest

This writes a .mcp.json to your project root that you can commit:

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

Teammates are asked to approve the server the first time they run claude in the repo. For how scopes and approvals work in general, see our Claude Code MCP guide.

Step 2: Verify the Connection

claude mcp list

You should see playwright with ✔ Connected. Inside a session, /mcp shows the same status plus the list of tools. If it says ✘ Failed to connect, jump to the troubleshooting table below.

Step 3: Run Your First Prompt

Name the tool explicitly the first time, otherwise Claude may try to write and run a Playwright script through the shell instead:

Use the playwright MCP to open https://mcp.so, search for "github",
and tell me the first three results.

A browser window opens (the server is headed by default), and you can watch Claude navigate. Claude Code asks permission before each new tool unless you allow it.

Useful Options

Every option goes after the package name in the launch command, or into the args array in .mcp.json. Each one also has a PLAYWRIGHT_MCP_* environment variable equivalent.

A headless, isolated Firefox setup looks like this:

claude mcp add playwright -- npx @playwright/mcp@latest \
  --headless --browser firefox --isolated

And the same in .mcp.json, with PDF and vision tools enabled:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--headless",
        "--isolated",
        "--caps=vision,pdf"
      ]
    }
  }
}

Capabilities in more detail

• vision adds coordinate-based mouse tools, for canvas apps or elements that do not show up well in the accessibility tree.
• pdf adds browser_pdf_save.
• devtools adds tracing, video recording and element highlighting.

The README also documents opt-in groups for network mocking, cookies and storage, configuration and test assertions. Only enable what you need: every extra tool is one more definition for Claude to consider.

Profiles and Logins

By default Playwright MCP uses a persistent profile, so logins survive between sessions. Profiles are stored per project:

• macOS: ~/Library/Caches/ms-playwright/mcp- followed by the channel and a workspace hash
• Linux: ~/.cache/ms-playwright/mcp- followed by the channel and a workspace hash
• Windows: %USERPROFILE%\AppData\Local\ms-playwright\mcp- followed by the channel and a workspace hash

Delete that folder to log out of everything. A persistent profile can be used by only one browser at a time, so if you run Claude Code in two terminals on the same project, give the second one --isolated or a different --user-data-dir.

If a task needs your real accounts, the --extension mode connects to tabs in your own Chrome or Edge instead of a separate browser. Be deliberate about this: anything Claude can do in the browser, it can do as you. Read MCP security best practices before pointing an agent at logged-in production accounts.

Example Prompts That Work Well

• "Use playwright mcp to open http://localhost:3000, sign up with a test email, and tell me if the welcome page loads without console errors."
• "Go to the pricing page, take a screenshot at 1280x720 and another with an iPhone viewport, and list layout differences."
• "Reproduce this bug report step by step in the browser and stop at the first step that fails."
• "Explore the checkout flow, then write a Playwright test in tests/checkout.spec.ts that covers the happy path."
• "Fill the contact form with sample data, submit it, and report the network response."

Troubleshooting

To see exactly which tools the server exposes and what they return, connect it to the MCP Inspector.

Running it in Docker instead

The README also ships a container image. It currently supports headless Chromium only:

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

If you already route servers through a gateway, see Docker MCP Gateway setup.

Playwright MCP vs Playwright CLI

The Playwright team is candid that coding agents may sometimes do better with the Playwright CLI and skills, because short CLI calls avoid loading large tool schemas and accessibility trees into context. MCP remains the better fit when Claude needs to keep a browser open and reason over the page step by step, such as exploratory testing or self-healing tests. In Claude Code, tool search already keeps unused tool definitions out of context, so MCP is a fine default for interactive browser work; consider the CLI for long, high-volume runs.

If you just need a simpler headless scraper, the Puppeteer MCP server is an alternative, but Playwright MCP is Microsoft's official, cross-browser option.

Next Steps

Once Playwright MCP is working, pair it with servers that close the loop: an issue tracker to read bug reports, or the GitHub MCP server to open a PR with the fix and a new test. Browse the MCP server directory for more, or read the full Claude Code MCP guide to manage everything you add.