How to Install Playwright MCP with Claude Code: Browser Automation in 2026

Playwright MCP lets Claude Code drive a real browser, navigate, click, fill forms, screenshot, read DOM, run JavaScript, instead of guessing what your web app does from reading the source. Once it's installed, Claude can iterate on a UI bug by actually loading the page and trying things, not by re-reading your CSS five times.

This is the install I run on a fresh machine in 2026. It takes about 10 minutes if nothing's already in place.

Quick reference

Why use Playwright MCP specifically

There are three browser-automation MCP servers worth knowing about in 2026:

Playwright MCP wins on three counts: it's officially maintained by Microsoft's Playwright team, it covers the full Playwright API (not just navigation), and it's the one Claude Code's own preview-tools are built on top of in spirit.

Step 1. Verify your Node version

node --version

If you see anything below 18.0.0, upgrade. The easiest path is nvm:

# macOS / Linux
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
nvm install 20
nvm use 20

# Windows
# Install nvm-windows from github.com/coreybutler/nvm-windows

Step 2. Install Playwright browsers

The MCP server doesn't bundle browser binaries. You need to install them once:

npx playwright install

This downloads Chromium, Firefox, and WebKit. About 400 MB total. If you only need Chromium:

npx playwright install chromium

Step 3. Add the MCP server to Claude Code

Open your Claude Code MCP config. The location depends on your OS:

For the Claude Code CLI specifically:

claude mcp add playwright -- npx -y @playwright/mcp@latest

That single command registers the MCP server. To verify:

claude mcp list

You should see playwright in the list.

If you prefer editing the config directly, add:

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

Restart Claude Code after editing the file.

Step 4. Confirm it works

Inside Claude Code, run:

/mcp

You should see playwright with a green status. Now ask Claude:

Use Playwright MCP to open google.com and tell me the page title.

You should see Claude call browser_navigate, then browser_snapshot or browser_evaluate, then return the title. If it hangs or errors, jump to the troubleshooting section.

What it can actually do

The current Playwright MCP exposes about 20 tools. The ones I use weekly:

• browser_navigate(url) — Go to a URL
• browser_snapshot() — Get the accessibility tree of the current page (fast, text-based, what Claude usually wants)
• browser_take_screenshot() — PNG screenshot
• browser_click(element) — Click by accessibility ref
• browser_type(element, text), Type into an input
• browser_evaluate(code), Run arbitrary JS in the page
• browser_network_requests(), Read recent network activity
• browser_console_messages(), Read console logs/errors
• browser_resize(width, height), Test responsive breakpoints

The accessibility-snapshot pattern is the one that makes Playwright MCP feel different from older browser-automation. Instead of dumping the full HTML (which blows context), it returns a structured tree of interactive elements with ref IDs. Claude then references elements by ref, not by CSS selector.

Real working examples

Example 1. Debug a CSS regression

The login button on localhost:3000 looks wrong on mobile. Use Playwright to load the page, resize to 375x812, take a screenshot, then read the button's computed styles.

Claude will navigate, resize, snapshot, screenshot, and run browser_evaluate to read computed styles. You see the actual rendered button instead of guessing from CSS.

Example 2. Verify a form submission

Test the signup form at localhost:3000/signup. Fill in test@example.com and password "TestPass123!", submit, and check for a success message or any console errors.

Claude does it. If the form silently fails, the console-messages tool catches it. If the network request fires but the response is 500, the network-requests tool catches it.

Example 3. Scrape a competitor page

Open example.com/pricing, snapshot the page, extract the pricing tiers into a JSON object.

This works. It's also the one that gets people in trouble, read the next section.

Security notes

Three things to know before pointing Playwright MCP at the internet:

1. The MCP runs as a local process with full filesystem access by default. A malicious page can't directly attack your machine through Playwright, but if you let Claude write the scraped data anywhere, watch where that goes. Don't write scraped HTML into project directories where it might end up in a commit.

2. Many sites' Terms of Service prohibit scraping. "Use Playwright to scrape LinkedIn" is technically possible. It's also a quick way to get your IP blocked and possibly worse depending on jurisdiction. Use this for sites you own, sites with explicit scraping permission, or your own test/staging environments.

3. CAPTCHA-bypass is not a use case. Playwright MCP is for legitimate automation. If you find yourself asking Claude to solve CAPTCHAs, you're using it wrong, either you should be using the site's official API, or you shouldn't be automating it.

For audit purposes, the source is at github.com/microsoft/playwright-mcp. Read the tool list before installing. The fact that Microsoft maintains it is a strong trust signal, but trust signals aren't substitutes for reading the code.

Troubleshooting

Symptom: MCP shows up but tool calls hang. Cause: Chromium didn't install correctly. Run npx playwright install chromium again and check for errors.

Symptom: "browser is not connected" errors. Cause: A previous Playwright instance crashed and is still holding the port. Kill stray Node processes (pkill -f playwright on macOS/Linux, Task Manager on Windows) and restart Claude Code.

Symptom: Headless browser launches but pages don't load. Cause: Some corporate firewalls block headless browser traffic. Try setting the MCP to non-headless mode by editing the args:

"args": ["-y", "@playwright/mcp@latest", "--headed"]

Symptom: The MCP works but Claude can't find elements. Cause: Usually a SPA that hasn't finished rendering. Tell Claude to call browser_wait_for with a selector or text before trying to click.

Symptom: "Cannot find module @playwright/mcp" on install. Cause: npm registry hiccup. Try npm cache clean --force then re-run the install command.

What's next

Once Playwright MCP is working, the next high-value MCP to add is usually filesystem or git, depending on what you're building. The point of MCPs is composability. Claude Code with Playwright + filesystem + git is a fundamentally different tool than vanilla Claude Code with no MCPs at all.

If you want to write your own MCP server (custom internal tooling, proprietary APIs), see our MCP builder skill guide for the starter template.

FAQ

Q: Does Playwright MCP work on Windows? A: Yes. Use the npx command above. The Windows-specific gotcha is that PowerShell sometimes mangles the args, if you hit issues, try Command Prompt or Windows Terminal with bash.

Q: Can I use Playwright MCP with Cursor or other LLM clients? A: Yes. Any MCP-compatible client works. Cursor supports MCPs as of late 2025. The install command differs slightly per client, but the underlying server is the same.

Q: Does it support recording browser sessions? A: Not directly, but Playwright's CLI does (npx playwright codegen URL). For MCP-driven recording, you'd export Claude's tool calls and replay them.

Q: Is it safe to run on production sites? A: Read-only operations (navigate, snapshot, screenshot, evaluate read-only JS) are safe. Anything that submits forms or clicks "delete" buttons should be tested on staging first. Treat Claude with browser access the way you'd treat an enthusiastic junior dev with prod creds.

Q: How does this compare to Claude's built-in preview-tools? A: Preview-tools are scoped to dev servers Claude itself starts. Playwright MCP can hit any URL, public web, local apps, internal tools you have credentials for. They're complementary, not competing.

For more Claude Code MCP setup guides, see our MCP install tutorials.