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.
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 withnode --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
- Step 1: In your terminal, inside the project folder, run the command at the top of this page.
- Step 2: Run
claude mcp listand look for playwright. The first check can take a few seconds whilenpxfetches the package. - 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."
- 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:
claude mcp add playwright -- npx @playwright/mcp@latest --headless| Flag | What it changes |
|---|---|
--headless | No browser window; faster, and works over SSH |
--browser firefox | Use Firefox, WebKit, Chrome or Edge instead of the default Chrome |
--device "iPhone 15" | Pretend to be a phone, for checking mobile layouts |
--isolated | Fresh profile in memory each session, nothing saved |
--caps vision,pdf,devtools | Extra 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
--isolatedto 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.jsonwith a saved login state. - Using your everyday Chrome with your real logins: add
--extensionand 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:
npx @playwright/mcp@latest --port 8931
claude mcp add --transport http playwright http://localhost:8931/mcpMicrosoft also publishes the image mcr.microsoft.com/playwright/mcp, which runs headless Chromium only.
If it does not work
| What you see | What to do |
|---|---|
playwright fails to connect in claude mcp list | Check 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 profile | Another session has the profile open. Close it, or add --isolated to this one. |
| No window appears on a remote machine | There is no display. Add --headless, or use the standalone server. |
| Flags seem to be ignored | They 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.