How to Connect Claude Code to Playwright with MCP

Connecting Claude Code to Playwright gives Claude a real browser it can drive: open pages, click, fill forms, read console errors and take screenshots. Microsoft's Playwright MCP server reads pages through accessibility snapshots, so Claude doesn't need screenshots or a vision model to understand a page.

Checked against: Microsoft's Playwright MCP README and Claude Code's MCP documentation on 28 October 2026. eSEOspace did not run these steps; menus can change, so follow the vendor's page if it differs.

Before you start

The README lists two requirements:

• Node.js 18 or newer.
• An MCP client, such as Claude Code.

Decide whether MCP is the right fit. Microsoft's README says modern coding agents "increasingly favor CLI-based workflows exposed as SKILLs over MCP." It points to the Playwright CLI for high-throughput coding work. Microsoft says MCP still suits "exploratory automation, self-healing tests, or long-running autonomous workflows" where a continuous browser session matters.

Steps

1. In your terminal, run Microsoft's command:

claude mcp add playwright npx @playwright/mcp@latest

1. Start claude. Claude Code launches the server as a local process when the session starts. There is no sign-in step.
2. Run /mcp to confirm the playwright server is listed with its tools.

Adding options

The README lists many command-line options, such as --headless, --isolated and --browser. Claude Code's docs say to put the whole launch command after --, so Claude Code passes flags to the server instead of reading them as its own. Built from that documented form:

claude mcp add playwright -- npx @playwright/mcp@latest --isolated --headless

Run claude mcp remove playwright first if you already added it without options.

Docker

Microsoft also publishes an image, which the README says supports only headless Chromium for now. Its config:

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

Claude Code's docs say to pass claude mcp add-json the object inside mcpServers, not the wrapper.

Check that it works

Run claude mcp list and look for ✔ Connected. The first run downloads the package, so it may take a moment.

Example prompts:

• "Open https://example.com with Playwright, take a snapshot and list the links on the page." (uses browser_navigate and browser_snapshot)
• "Go to my staging homepage and report any console errors." (uses browser_console_messages)
• "Take a full-page screenshot of the pricing page and save it." (uses browser_take_screenshot)

These are good fits for website QA. See Claude Code website QA for a wider checklist.

Permissions and safety

The README's security section is one line: Playwright MCP "is not a security boundary." It links to the MCP project's security best practices. Plan around that.

• Browser profile. The default persistent profile stores logins like a normal browser. Use --isolated to keep it in memory and discard it on close.
• File access. By default, file access is limited to workspace root directories and file:// URLs are blocked. --allow-unrestricted-file-access removes that limit, so leave it off. Claude Code answers the server's roots request with your session's working directories.
• Origin filters. --allowed-origins and --blocked-origins exist, but the README says they do "not serve as a security boundary" and don't affect redirects.
• Code in the page. browser_evaluate and browser_run_code_unsafe run JavaScript. Keep those on ask in Claude Code with a permission rule such as an ask rule for mcp__playwright__browser_run_code_unsafe.
• Network exposure. Running with --host 0.0.0.0 lets any client that can reach the port use it.

Web pages are untrusted input that can carry hidden instructions. Read prompt injection in Claude Code, exposed local MCP servers and the MCP Security Center.

If it doesn't work

Microsoft's README doesn't include a troubleshooting section for Claude Code, so these are general checks plus Claude Code's documented behavior:

• Node too old. Check node --version is 18 or newer.
• Flags ignored or rejected. Make sure server options come after -- in the claude mcp add command.
• Server exits. Claude Code's docs say a stdio server that exits or fails to start shows as failed in /mcp, with detail on why. Run the npx @playwright/mcp@latest command in a terminal to see its error.
• Wrong browser. Choose one with --browser. The README lists chrome, firefox, webkit and msedge.
• Docker only gives Chromium. That's documented: the image supports only headless Chromium for now.

Next step

Read the Playwright MCP server profile for the opt-in tool groups. For a different browser approach, see Claude Code with Chrome. Other setups are in the connection guides hub, including VS Code with Playwright.

Frequently asked questions