Skip to content
MCP Shelf

Pod to App: Claude Code

How to install the Playwright MCP server in Claude Code

By Sophie Filer · Updated 10 Nov 2026 · Steps checked against Playwright's own docs on 10 Nov 2026

The short answer

Run claude mcp add playwright npx @playwright/mcp@latest in your terminal. Claude Code starts the server itself when it needs a browser, so there is no separate download step; a Chrome window opens the first time it browses.

Terminal
claude mcp add playwright npx @playwright/mcp@latest
Needs
Node.js 18 or newer
Sign-in
None
Runs on
Your machine
Price
Free, Apache 2.0

Before you start

  • Node.js 18 or newer, since Claude Code launches the server with npx. Check with node --version.
  • A desktop session, if you want to watch the browser. On a server with no screen, use headless mode or the standalone server below.

Install it step by step

  1. Step 1: In your terminal, inside the project folder, run the command at the top of this page.
  2. Step 2: Run claude mcp list and look for playwright. The first check can take a few seconds while npx fetches the package.
  3. Step 3: Open Claude Code and ask something that needs a real page: "Go to localhost:3000, sign up with a test email and tell me what breaks."
  4. Step 4: Watch the browser window it opens. Claude Code reads each page as an accessibility snapshot, then clicks and types by element, not by screen position.

Pass options after a double dash

Flags for the Playwright server go at the end, after --, so Claude Code does not read them as its own. For example, to run without a visible window:

Terminal
claude mcp add playwright -- npx @playwright/mcp@latest --headless
FlagWhat it changes
--headlessNo browser window; faster, and works over SSH
--browser firefoxUse Firefox, WebKit, Chrome or Edge instead of the default Chrome
--device "iPhone 15"Pretend to be a phone, for checking mobile layouts
--isolatedFresh profile in memory each session, nothing saved
--caps vision,pdf,devtoolsExtra tools: clicking by screen position, saving PDFs, and developer tools

To change flags later, run claude mcp remove playwright and add it again with the new ones.

Logins, profiles and two sessions at once

By default the server keeps one browser profile per workspace, so cookies and logins survive between Claude Code sessions. On macOS it lives under ~/Library/Caches/ms-playwright. That profile can only be open in one browser at a time, so a second Claude Code session in the same folder will clash with the first.

  • Running two sessions in parallel: add --isolated to the second one, or give it its own --user-data-dir.
  • Testing a logged-in flow from a clean start: use --isolated --storage-state=auth.json with a saved login state.
  • Using your everyday Chrome with your real logins: add --extension and install the Playwright Extension in Chrome or Edge.

On a server or in Docker

Where Claude Code runs without a display, either keep --headless, or start the server once on its own port and connect to it by URL:

Terminal: start the server, then connect Claude Code
npx @playwright/mcp@latest --port 8931
claude mcp add --transport http playwright http://localhost:8931/mcp

Microsoft also publishes the image mcr.microsoft.com/playwright/mcp, which runs headless Chromium only.

If it does not work

What you seeWhat to do
playwright fails to connect in claude mcp listCheck node --version is 18 or higher, and that npx @playwright/mcp@latest --help runs on its own.
"Browser is already in use" or a locked profileAnother session has the profile open. Close it, or add --isolated to this one.
No window appears on a remote machineThere is no display. Add --headless, or use the standalone server.
Flags seem to be ignoredThey must come after --. Remove the server and add it again in the right order.

MCP Shelf take

Is Playwright worth adding to Claude Code?

Playwright MCP is the easiest way to let Claude Code check its own work in a real browser: build the form, open it, fill it in, read the error. That loop is where it shines, along with poking around sites with no API. Be aware that Microsoft's own README now suggests the Playwright CLI with skills for coding agents, because page snapshots eat context fast. Our view: install the MCP server for exploratory checks and longer sessions, and switch to plain Playwright tests once you know what you want to test repeatedly.

Sophie Filer

Questions

Do I need to install Playwright browsers first?

Usually not. The server uses Chrome by default and npx fetches the package on first run. If you pick another browser with --browser and it is missing, the server will say so and you can install it then.

Can Claude Code use Playwright without opening a window?

Yes. Add the server with -- npx @playwright/mcp@latest --headless and the browser runs out of sight. You lose the chance to watch what it does, which is often handy for debugging.

Does Playwright MCP keep me logged in between sessions?

Yes, by default. It saves a browser profile per workspace, so logins persist. Use --isolated when you want every session to start clean.

Should I use Playwright MCP or the Playwright CLI with Claude Code?

The README points coding agents towards the CLI with skills when token use matters, since it avoids loading big page snapshots. The MCP server suits open-ended exploring and long agent loops where keeping the browser state matters more.

Sources: the steps on this page are written in our own words from Playwright MCP's own install docs, the README. If they disagree with this page, the project's docs win; please tell us from the server page.