Setup Playwright MCP with Claude Code

This tutorial is for the moment when GitHub or docs context stops being enough and you need the agent to actually touch a page.

That makes Playwright MCP a very different setup from repo-first MCP servers. If the install works, you should be able to watch Claude Code open a browser, navigate to a real URL, interact with elements, and report what happened. If the install does not work, the failure usually comes from one of three places: the way Claude starts the server, the way npx behaves on your OS, or the browser session mode you chose.

The goal here is not to build the fanciest browser stack. It is to get one clean first run in Claude Code, then decide whether browser automation actually belongs in your MCP stack.

Fast Answer#

• The shortest default path is claude mcp add playwright npx @playwright/mcp@latest.
• On native Windows, treat the cmd /c npx -y ... wrapper as the safer path. Anthropic documents that npx-based local MCP servers otherwise hit Connection closed failures on Windows.
• Start with the public TodoMVC demo from the Playwright docs before trying your own app.
• Keep the browser headed for the first run so you can see what the server is doing.
• Move to the standalone HTTP server only if local client execution is the unstable part.

What To Prepare Before You Add Anything#

You do not need much for the first run, but you do need the right few things:

1. Claude Code installed and working in a normal project directory.
2. Node.js 18 or newer.
3. One terminal session where Claude Code already opens cleanly.
4. One public browser task you can verify without logging in.

The public task matters more than people expect. If the first run depends on your company's app, a flaky VPN, auth state, or a page that only works with hidden setup steps, you will not know whether Playwright MCP is broken or your environment is just noisy.

The official Playwright docs use https://demo.playwright.dev/todomvc as the first interaction example. That is the right starting point because the page is public, interactive, and easy to judge without inventing complicated prompts.

Click to enlarge

Official Playwright Docs screenshot checked on 2026-04-10. This is the real setup surface for the first install path and the TodoMVC proof task.

Click to enlarge

This flow keeps the stack narrow: add one browser server, verify Claude can see it, run one public page task, and only then decide whether you need the standalone HTTP server or extra browser flags.

Start With The Shortest Local Install#

Playwright's docs give the standard server definition:

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

Playwright then gives the Claude Code equivalent as a direct CLI command:

claude mcp add playwright npx @playwright/mcp@latest

This should be the default first route on macOS, Linux, and WSL. It is the smallest path between "I have Claude Code" and "Claude can drive a browser."

After you add it, verify the registration immediately:

claude mcp list
claude mcp get playwright

If the server shows up there, do not keep reconfiguring it. Move to the first task. A lot of people waste time polishing config before they know whether the basic connection already works.

Native Windows Needs A Different Command#

Anthropic's MCP docs include one important Windows note: local MCP servers that rely on npx should be wrapped with cmd /c on native Windows. Without that wrapper, Claude Code can hit Connection closed errors because Windows does not execute npx the same way Unix shells do.

Playwright's docs do not spell out a separate Windows-specific Claude command, but combining Anthropic's Windows rule with the Playwright package gives the safer native Windows form:

claude mcp add --transport stdio playwright -- cmd /c npx -y @playwright/mcp@latest

That command is a direct synthesis of the two official docs, not a random workaround.

Use it when all three of these are true:

• you are on native Windows, not WSL
• Claude Code is starting the server locally
• the plain npx command either fails or closes immediately

If you are in WSL, treat it like Linux and try the simpler local install first.

Keep The First Browser Session Visible#

For the first run, do not optimize for stealth or speed. Optimize for visibility.

The Playwright docs say headed mode is the default. Keep it that way at first. A visible browser tells you three critical things quickly:

• whether the server actually launched a browser
• whether navigation is happening on the expected page
• whether the page state matches what Claude reports back

Headless mode is useful later. It is a bad default for the first proof run because it removes the easiest debugging surface you have.

Run One Public Proof Task Before Touching Your Own App#

Once Claude Code can see the server, give it one task that the official Playwright docs already use as a first interaction.

First Browser Task In Claude Code#

Use Playwright MCP only.

1. Navigate to https://demo.playwright.dev/todomvc
2. Add these todo items:
   - Review Playwright MCP install
   - Confirm Claude can control the browser
3. Tell me what you clicked or typed
4. Count how many active todo items remain
5. Take a screenshot before you finish
6. Stop if the page fails to load or the browser tools are unavailable

This is intentionally plain. The test is not whether Claude can improvise a complex workflow. The test is whether browser navigation, typing, state changes, and one screenshot all work in one loop.

Good first-run success looks like this:

• a browser window actually opens
• Claude reaches the TodoMVC page without asking for extra setup
• the items appear in the list
• the result matches the visible page state

Bad first-run signals look like this:

• Claude cannot see any Playwright tools
• the server appears in claude mcp list but browser actions fail immediately
• the browser opens and then hangs before the page becomes interactive
• Claude describes actions that never happened on screen

If you get the bad path, stop and debug the install. Do not jump straight into a login-heavy internal app.

When To Use The Standalone HTTP Server Instead#

Playwright's docs include a second route for cases where the browser should run as a separate HTTP MCP server:

npx @playwright/mcp@latest --port 8931

Then the client points to:

http://localhost:8931/mcp

Claude Code's own MCP docs support remote or local HTTP servers through claude mcp add --transport http ..., so the combined Claude route is:

claude mcp add --transport http playwright http://127.0.0.1:8931/mcp

That path is worth it when the problem is not Playwright itself but how the client launches local processes. It is also cleaner when you want to restart the Playwright server explicitly, keep the browser process separate, or run the browser on a machine where the MCP client is not the right place to host it.

It is not the best first move if the simple local command already works.

Three Flags Worth Knowing Early#

Most people do not need advanced configuration on day one, but these three options matter fast:

• --headless when you no longer need the visible browser
• --browser=firefox or another browser choice when Chrome-default behavior is not enough
• --isolated when you want a fresh session instead of a persistent profile

That last one matters more than it sounds. Playwright MCP uses a persistent profile by default, which is convenient after setup but can blur the line between "the server works" and "my old browser state made this test pass."

If you are trying to verify a clean reproduction path, isolated mode is often the better second test.

What Usually Breaks This Setup#

These are the common failure patterns that are actually worth checking:

• Claude never shows a playwright server because the add command failed silently
• native Windows is using plain npx instead of the cmd /c wrapper
• the first task depends on login state, popups, or company-specific network access
• the browser is running headless, so you lose the easiest debugging signal
• a persistent profile keeps stale cookies or old session state that confuse the result
• the user adds Playwright MCP before deciding whether browser action is even the real bottleneck

Most of those failures are self-inflicted. The fix is usually to narrow the test again.

When This Stack Is Actually Worth Keeping#

Keep Playwright MCP with Claude Code in your working stack when browser action keeps appearing in real tasks:

• reproduce a UI bug
• verify a multi-step flow after a code change
• collect browser evidence before writing a fix
• inspect a live page that repo context alone cannot explain

Do not keep it just because the demo was impressive. Browser automation adds weight. It earns that weight only when browser evidence is part of the normal job.

If your real need is still repository context rather than browser action, go back to GitHub MCP Server or the broader decision page How To Choose An MCP Server For GitHub Workflows.

Official References#

These sources shaped the setup above:

• Playwright Docs: Playwright MCP
• Anthropic Docs: Connect Claude Code to tools via MCP
• Playwright MCP Repository

Next Step#

If you want the broader MCP choice logic, read How To Choose An MCP Server For GitHub Workflows.

If the install still feels broken at the host or transport level, open Common MCP Server Setup Mistakes.

If the next question is still host choice rather than browser setup, read Cursor vs Claude Code.