Blog
3 min read

Playwright MCP: Let Claude Code Use a Real Browser

The Playwright MCP server lets AI tools open pages, click, type and read a live browser through accessibility snapshots instead of screenshots. How to add it to Claude Code, useful prompts for testing and debugging, key options like headless and isolated, and its limits.

One of the most useful things you can give an AI coding tool is eyes on your running app. The Playwright MCP server does that: it lets Claude Code (or Cursor, VS Code and others) drive a real web browser.

What it is

Playwright is Microsoft's browser automation library, widely used for end-to-end tests. Playwright MCP is an MCP server, also from Microsoft, that exposes Playwright as tools an AI can call: navigate to a URL, click, type, fill a form, take a snapshot, read console messages.

The clever part: instead of looking at screenshots, the AI reads a structured accessibility snapshot of the page — the buttons, links, inputs and text, each with a reference it can act on. That's faster and more reliable than guessing from pixels, and it doesn't need a vision model.

Add it to Claude Code

You need Node.js installed. Then, in your terminal:

claude mcp add playwright npx @playwright/mcp@latest

Start Claude Code and run /mcp to check it's connected. The first run may download a browser. (Connecting MCP servers to Claude Code)

Things to ask it

Start your app (npm run dev), then:

Open http://localhost:3000, sign up with a new test account, and tell me if anything breaks. Check the browser console for errors.

Go to the pricing page at mobile width (390px) and describe any layout problems.

Reproduce this bug: clicking "Save" on /settings twice creates two records. Then fix it and verify the fix in the browser.

Fill in the contact form with an invalid email and confirm the error message appears.

The last two are the real win: Claude can change the code and check the result itself, instead of you being the one who refreshes and reports back. (Claude Code best practices)

Useful options

Add flags after the package name:

claude mcp add playwright npx @playwright/mcp@latest --headless --isolated
  • --headless — no visible browser window (needed on servers). By default a window opens so you can watch.
  • --isolated — keep the browser profile in memory and throw it away afterwards; useful if several sessions run at once.
  • --browser — chrome, firefox, webkit or msedge.
  • --caps vision — add coordinate-based clicking for pages where the snapshot isn't enough.

Running it on a server

On a Linux server with no display, use --headless. You may also need the browser's system libraries installed (npx playwright install-deps chromium on Debian/Ubuntu).

Limits and cautions

  • It's a real browser with real sessions. If it's logged into something, the AI can act as you. Use test accounts and --isolated.
  • Pages can contain instructions. A web page the AI visits could include text designed to manipulate it. Be careful pointing it at untrusted sites while it also has powerful tools. (Prompt injection)
  • Snapshots of huge pages are large and use context. Point it at specific pages, not "browse the whole site".
  • It's not a test suite. Great for exploring and verifying; for checks you want to run on every change, ask Claude to turn what it found into proper Playwright tests. (Playwright tutorial)

The summary

  • Playwright MCP gives AI tools a real browser, read through accessibility snapshots.
  • Add it with claude mcp add playwright npx @playwright/mcp@latest.
  • Best use: let the AI verify its own UI changes and reproduce bugs.
  • Use test accounts, --isolated, and --headless on servers.

EasySpawn runs Claude Code and your app on the same server, so the agent can start your app, open it in a headless browser and check its own work without anything running on your laptop. See how it works or join the waitlist.

Related: Playwright Tutorial · The Best MCP Servers for Coding · Browser Developer Tools for Beginners · How to Test Your App Before Launch

Keep reading