Playwright MCP — Use Cases, Install & Live Demo

Name: Playwright MCP Server
Author: microsoft

Why use it

Key features

First-party — published and maintained by Microsoft Playwright team
Accessibility-tree based — much more reliable than pixel-based browser agents
Supports Chromium, Firefox, WebKit, headed or headless
Multi-tab, file uploads/downloads, network interception, video recording

Live Demo

What it looks like in practice

playwright.replay ▶ ready

0/0

Install

Pick your client

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

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

Open Claude Desktop → Settings → Developer → Edit Config. Restart after saving.

~/.cursor/mcp.json · .cursor/mcp.json

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

Cursor uses the same mcpServers schema as Claude Desktop. Project config wins over global.

VS Code → Cline → MCP Servers → Edit

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

Click the MCP Servers icon in the Cline sidebar, then "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

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

Same shape as Claude Desktop. Restart Windsurf to pick up changes.

~/.continue/config.json

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

Continue uses an array of server objects rather than a map.

~/.config/zed/settings.json

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

Add to context_servers. Zed hot-reloads on save.

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

One-liner. Verify with claude mcp list. Remove with claude mcp remove.

Use Cases

Real-world ways to use Playwright

Smoke-test a production deploy in 60 seconds

👤 DevOps engineers, release managers ⏱ ~5 min intermediate

When to use: You just shipped a deploy and want a quick gut-check that the critical user flows still work, before declaring success.

Prerequisites

Test account credentials (use a dedicated QA account, not real user) — Store in env vars or in your prompt itself

Flow

Open the home page and verify it loads

Open https://app.example.com. Verify the page returns 200, the H1 says 'Welcome', and the login button is visible.✓ Copied

→ Pass/fail with screenshot if it fails
Run the login → core action → logout flow

Log in as [email protected] / [password]. Then create a new project named 'smoke-test-<timestamp>'. Then delete it. Then log out.✓ Copied

→ Each step succeeds; if any fails, screenshot + DOM dump
Diagnose any failure

If a step failed, capture the page snapshot and tell me what's different from a working baseline.✓ Copied

→ Specific element or network request that broke

Outcome: Confidence (or rapid panic) about your deploy in under a minute, without needing a full E2E suite.

Pitfalls

Hard-coded test data accumulates and pollutes prod — Always use unique timestamps in test data and clean up at the end of the flow
Browser session persists between runs, masking bugs that need a clean state — Run with --browser-context: incognito or clear cookies between runs

Combine with: sentry

Audit your site at 5 viewport widths and report breakage

👤 Frontend engineers, designers ⏱ ~15 min intermediate

When to use: Before shipping a marketing site or product page, you want to verify it doesn't break at common widths.

Flow

Open the page at 5 viewport widths (320, 375, 768, 1024, 1440)

Open https://example.com at viewports 320×568, 375×812, 768×1024, 1024×768, 1440×900. Take a full-page screenshot of each.✓ Copied

→ 5 screenshots saved
Detect horizontal overflow at each width

For each viewport, list any elements where scrollWidth > viewportWidth. These are causing horizontal scroll and feel broken.✓ Copied

→ Per-viewport list of offending CSS selectors
Suggest fixes

For each overflow element, get its computed CSS and suggest the smallest fix (probably max-width, overflow-wrap, or breakpoint adjustment).✓ Copied

→ Actionable diff per element

Outcome: A prioritized fix-list with specific selectors, suitable to file as a single PR.

Pitfalls

Real users have scrollbars (15px on Windows), which the headless browser doesn't simulate by default — Test with both --browser=chromium and --browser=webkit; widths matter more than you think

Combine with: chrome-devtools · filesystem

Crawl your site and find every broken internal link

👤 Documentation maintainers, SEO managers ⏱ ~30 min intermediate

When to use: Before a marketing push or once a quarter — silent 404s on internal links hurt SEO and user trust.

Flow

Crawl the site collecting all internal links

Starting from https://docs.example.com, crawl all pages on the same domain (depth 3 max). Collect every href found.✓ Copied

→ Complete link inventory
Test each link

For each unique URL, send a HEAD request and capture the status code. Flag anything >= 400.✓ Copied

→ List of broken links with status codes
Group broken links by referrer

For each broken link, list which page(s) link to it, so I know where to fix.✓ Copied

→ Per-broken-link list of referrers, ordered by referrer count

Outcome: A markdown report you can hand to the docs team listing every broken link grouped by which page needs fixing.

Pitfalls

Some sites rate-limit aggressive crawlers — Add delay between requests; if running on production, do it during off-peak hours

Combine with: filesystem · github

Scrape data that requires authentication

👤 Data analysts, researchers ⏱ ~20 min advanced

When to use: The data you need lives behind a login (your own admin dashboard, internal reports, etc.) and basic scrapers can't reach it.

Prerequisites

Valid credentials for the target — Use a service account, never your personal one

Flow

Log in

Open https://target.example.com/login. Fill the email field with [email] and password with [password]. Submit.✓ Copied

→ Confirmed session — landed on dashboard URL
Navigate to the data page

Click into the Reports section. Wait for the data table to render.✓ Copied

→ Table visible in DOM
Extract the data

Read every row of the report table. Return as JSON with each column as a key.✓ Copied

→ Complete dataset as JSON

Outcome: Structured data you couldn't have gotten with a simple HTTP scraper, ready to drop into a spreadsheet or DB.

Pitfalls

MFA is enabled and breaks the flow — Set up an app-specific password if the service supports it, or use a long-lived API token instead
Captchas appear after multiple logins — Use a persistent browser context (--user-data-dir) so cookies are reused and you don't trigger captcha gates

Combine with: postgres · filesystem

Combinations

Pair with other MCPs for X10 leverage

playwright + filesystem

Scrape a site, save each page's content to disk for offline RAG

Crawl docs.stripe.com starting from /api, save each page as a Markdown file under ./knowledge/stripe/{path}.md.✓ Copied

playwright + chrome-devtools

Performance + functional testing in one flow — verify the page loads correctly AND fast

Open my landing page. Verify the H1, then capture a Lighthouse trace and tell me if LCP is under 2 seconds.✓ Copied

playwright + sentry

Reproduce a production error reported in Sentry by replaying user breadcrumbs

Sentry issue WEB-3a91 says the user clicked X then Y then crashed. Reproduce that exact sequence in Playwright and confirm.✓ Copied

Tools

What this MCP exposes

Tool	Inputs	When to call	Cost
browser_navigate	url: str	Navigate to a URL — first action of any flow	1 page load
browser_snapshot		Get a structured view of all interactive elements (links, buttons, inputs)	free
browser_click	ref: str (from snapshot) \| selector: str	Click on an element identified by snapshot ref or CSS selector	free
browser_type	ref, text, submit?: bool	Fill an input field; with submit:true also presses Enter	free
browser_screenshot	fullPage?: bool, path?: str	Capture visual evidence — debugging or audit	disk space
browser_evaluate	script: str	Run arbitrary JS in the page context — use sparingly, prefer specific tools	free
browser_network_requests		Inspect what the page is loading; useful for finding hidden API endpoints	free

Cost & Limits

What this costs to run

API quota: Free — runs locally, only your machine resources
Tokens per call: Snapshots are 500-3000 tokens depending on page complexity
Monetary: Free. Browser binaries downloaded once (~300MB Chromium).
Tip: Use browser_snapshot instead of screenshots — it's 100× cheaper in tokens and more reliable for Claude to act on.

Security

Permissions, secrets, blast radius

Credential storage: Pass via env vars; never put real production credentials in prompts

Data egress: Browsers connect to whatever URLs you navigate to. No telemetry to Microsoft.

Browser sessions persist — clear cookies between runs if you're testing auth.
Headed mode opens a real window on your machine; use headless for CI.

Troubleshooting

Common errors and fixes

Element not found / TimeoutError

The page hasn't finished rendering. Add an explicit wait: browser_wait_for(selector) or browser_wait_for(text='...') before the action.

Verify: Take a snapshot first to see what's actually on the page

Browser fails to launch on Linux

Install OS deps: npx playwright install-deps. Common in Docker — use the official Playwright image as base.

Verify: playwright --version

All navigations fail with net::ERR_*

Network sandboxing issue. Run with --no-sandbox if in Docker, or check your firewall / proxy.

Site detects automation and shows captcha

Use --browser-type=firefox (less detected than headless Chromium), or run headed if appropriate. Some sites are intentionally bot-resistant — respect that.

Alternatives

Playwright vs others

Alternative	When to use it instead	Tradeoff
puppeteer MCP	You only need Chromium and want a slightly simpler API	Chromium-only; no Firefox/WebKit; smaller community now
Firecrawl MCP	You just need to extract content, not interact with the page	Hosted (costs credits) but zero infra; can't click through flows
Browserbase MCP	You need to run browser automations from a serverless context (no local browser)	Hosted service with per-minute pricing; great for production agents

More

Resources

📖 Read the official README on GitHub

🐙 Browse open issues

🔍 Browse all 400+ MCP servers and Skills