DEV Community

Yuvaraj
Yuvaraj

Posted on

Playwright MCP on Windows with a local browser — what actually works

#playwright #mcp #agents #microsoft

I tried set up browser automation in an agentic IDE, a colleague sent me this config from the docs:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest", "--browser", "msedge"]
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

"Works on my Mac, with my local browser" colleague said.

It did not work on Windows. And fixing it turned out to be a two-hour journey through three dead ends before I found what actually works. This is that story.

What Playwright MCP does

Before the errors, a quick picture of what we are setting up.

Playwright MCP is a Model Context Protocol server. It sits between your agentic IDE and a real browser. The IDE calls tools — browser_navigate, browser_snapshot, browser_click — and the MCP server turns those calls into actual browser actions via Playwright.

Agentic IDE  -->  playwright-mcp process  -->  Edge / Chrome
             <--                          <--
Enter fullscreen mode Exit fullscreen mode

On Mac with a locally installed binary and Chrome, this works without thinking about it. On Windows, especially on a corporate machine, it does not.

One thing to be clear about upfront: this article is about using your already-installed browser — Edge, Chrome, whatever you have — instead of letting Playwright download and manage its own browser binaries.

If you are on a machine where you can freely run npx playwright install, the standard docs work fine.

The error nobody explains

The MCP panel shows the server as connected. You ask the AI to open a page. It calls browser_navigate. The response:

Error: No client available
Enter fullscreen mode Exit fullscreen mode

Not "browser not found." Not "executable path wrong." Just: no client available.

What this actually means: the MCP server process started fine, but when it tried to launch a browser at startup, something failed silently. The process is alive. It has no browser attached to it. The first tool call exposes this.

Here is the sequence of what actually happens:

Agentic IDE         playwright-mcp process        Edge

    |                       |                        |
    |--- spawn process----> |                        |
    |                       |--- launch browser ---> |
    |                       |                  FAIL  |
    |                       |  (silent, no crash)    |
    |                       |                        |
    |--- browser_snapshot-> |                        |
    |                       |                        |
    | <-- No client available                        |
Enter fullscreen mode Exit fullscreen mode

The process stays up. The MCP handshake completes. Tools register. Nothing tells you the browser never launched. You only find out when you try to use it.

Why it fails on Windows with npx

When you run npx @playwright/mcp@latest, Playwright looks for its managed browser binaries — a local cache of Chromium, Firefox, and WebKit builds that live at %LOCALAPPDATA%\ms-playwright on Windows. This cache is populated by running npx playwright install.

On a corporate Windows machine, that download is blocked. Playwright finds nothing in the cache, skips the browser launch, and waits. No error. No warning. Just silence.

This is not an obscure edge case. The microsoft/playwright-mcp GitHub repository has multiple open issues around exactly this:

  • Issue #13 — "[Windows] Error: chrome is not found" — npx invocation cannot find browser without Playwright binary install
  • Issue #1017 — "Problems running locally" — general Windows local browser failures
  • "Missing prerequisite steps in Getting Started documentation" — the docs assume the managed browser cache exists

The docs tell you to run npx @playwright/mcp@latest. They do not tell you that this requires the Playwright browser cache to already be in place.

Dead end 1: point at the local Edge binary

There is a flag for this. --executable-path takes the path to any browser binary:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "-y", "@playwright/mcp@latest",
        "--browser", "msedge",
        "--executable-path",
        "C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe"
      ]
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Same error. The executable path is parsed, but the internal validation still checks Playwright's local cache before attempting to launch. With a broken or incomplete playwright-core install — and @playwright/mcp depends on an alpha version of it — the launch fails before the executable path is reached.

Dead end 2: global install

Maybe npx is the problem. Install it once, use the binary directly:

npm install -g @playwright/mcp
Enter fullscreen mode Exit fullscreen mode

Then look for:

C:\Users\<you>\AppData\Roaming\npm\playwright-mcp.cmd
Enter fullscreen mode Exit fullscreen mode

It is not there.

The package.json for @playwright/mcp declares:

"bin": {
  "playwright-mcp": "cli.js"
}
Enter fullscreen mode Exit fullscreen mode

So playwright-mcp.cmd should exist. When it is absent, the global install was incomplete. @playwright/mcp depends on playwright-core at version 1.64.0-alpha-.... Corporate npm registries typically mirror stable packages, not alpha builds. The install appears to succeed, the package files land, but the .cmd shim is never created.

Dead end 3: call cli.js directly via node

The files are there even if the shim is not. So:

{
  "mcpServers": {
    "playwright": {
      "command": "node",
      "args": [
        "C:\\Users\\...\\AppData\\Roaming\\npm\\node_modules\\@playwright\\mcp\\cli.js",
        "--executable-path",
        "C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe"
      ]
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Same error. The cli.js entry point does this:

const { tools, libCli } = require('playwright-core/lib/coreBundle');
Enter fullscreen mode Exit fullscreen mode

If playwright-core is broken, this require throws internally. The MCP protocol layer initializes before the browser, so the server comes up, tools register, and the first browser call fails.

What actually works: --port and HTTP transport

The npm README has one paragraph about this, tucked under a heading called "Standalone MCP server":

When running headed browser on system w/o display or from worker processes of the IDEs, run the MCP server from environment with the DISPLAY and pass the --port flag to enable HTTP transport.

"Worker processes of the IDEs" is exactly what we are dealing with.

The fix is to stop letting the IDE spawn the browser process. Run it yourself, then connect the IDE to it over HTTP.

Step 1 — open a terminal and start the server:

npx @playwright/mcp@latest --executable-path "C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe" --port 8931
Enter fullscreen mode Exit fullscreen mode

Edge opens. The terminal shows the server is listening. Leave it running.

Step 2 — connect the IDE via URL, not command:

{
  "mcpServers": {
    "playwright": {
      "url": "http://localhost:8931/mcp"
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

No command. No args. No binary path. The IDE connects over HTTP to the /mcp endpoint. It works.

Why this works when nothing else did

When you run the server yourself in a terminal, npx runs in your shell's Node environment — not inside the IDE's sandboxed process. Your shell hits the public npm registry directly. The alpha playwright-core resolves. --executable-path is honoured. Edge launches.

The IDE never touches the Node or npm layer at all. It sends HTTP requests to a port. The transport is completely decoupled from the browser launch problem.

Terminal (your shell)
    |
    npx @playwright/mcp@latest --executable-path "...msedge.exe" --port 8931
    |-- downloads alpha playwright-core (public registry, works)
    |-- launches Edge via --executable-path (works)
    |-- listens on :8931/mcp

Agentic IDE
    |
    url: http://localhost:8931/mcp
    |-- browser_navigate, browser_snapshot, etc over HTTP
    |-- never touches npx, never touches node_modules
Enter fullscreen mode Exit fullscreen mode

Why Mac does not need this

On Mac, a working setup looks like this:

{
  "mcpServers": {
    "playwright": {
      "command": "/path/to/project/node_modules/.bin/playwright-mcp",
      "args": [
        "--executable-path",
        "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
      ]
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

This is a locally installed binary from a real project's node_modules — not a global install, not npx. When you run npm install inside a real project, the full dependency tree resolves including native binaries for macOS. The .bin/playwright-mcp shell script is intact, playwright-core is complete, and --executable-path points directly at Chrome without hitting the cache problem.

The same works on Windows if you do a local project install and your corporate registry carries the alpha playwright-core. If it does not, you end up back at "no client available." The --port approach sidesteps this entirely.

Skipping the manual terminal step

Running a terminal before every IDE session is annoying. A few options depending on how much you want to automate it.

A .bat file on your desktop:

@echo off
start /min cmd /c npx @playwright/mcp@latest ^
  --executable-path "C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe" ^
  --port 8931 > "%TEMP%\playwright-mcp.log" 2>&1
echo Playwright MCP started
Enter fullscreen mode Exit fullscreen mode

One double-click before opening the IDE. The window minimizes immediately and keeps running in the background.

Windows Task Scheduler at login:

  • Program: cmd.exe
  • Arguments: /c npx @playwright/mcp@latest --executable-path "C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe" --port 8931

Zero daily effort. The server is always ready when you log in.

IDE session hook — the cleanest option:

If your agentic IDE supports session lifecycle hooks, this is the best approach. Wire the npx command as a session start hook and the IDE auto-starts the server every time it opens. No terminal, no bat file, no Task Scheduler. The IDE takes care of it.

For example, in Bob (IBM's agentic IDE), you add this to your settings:

{
  "hooks": {
    "session": {
      "start": [
        {
          "command": "cmd /c start /min cmd /c npx @playwright/mcp@latest --executable-path \"C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe\" --port 8931"
        }
      ]
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Open the IDE, the hook fires, Edge launches, the MCP server is ready. You just open Bob and start working.

The config, one more time 

# Run this once before opening your IDE (or skip if using a hook)
npx @playwright/mcp@latest --executable-path "C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe" --port 8931
Enter fullscreen mode Exit fullscreen mode 
{
  "mcpServers": {
    "playwright": {
      "url": "http://localhost:8931/mcp"
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

No Playwright browser cache. No corporate registry bypass. No CDP. A server you start once, and an IDE that connects to it over HTTP.

One more thing Windows taught me

After all of this — the right command, the right URL, the hook firing, Edge open, everything looking good — the MCP panel in the IDE still showed "disconnected."

I spent another ten minutes checking the config. Re-reading the docs. Wondering what I had missed.

Then, out of sheer desperation, I did what every Windows user eventually does: I closed the IDE and reopened it.

Voila! Connected. :D

No explanation. No error. No reason.

Just Windows being Windows, politely reminding you that the solution to most problems is to turn it off and turn it back on again.

So if you have followed every step here and the panel still says disconnected — close the IDE, reopen it. You're welcome ;).

I spent two hours on this because the error message gave nothing away, and every suggestion online assumed the Playwright browser cache was available. If you are on a corporate Windows machine and you hit "no client available," the problem is not your config — it is the transport. Switch to --port and you are done.

If this helped, or if you hit a different wall I did not cover, let me know in the comments.

Top comments (0)