What Is Playwright MCP?#

Playwright MCP wraps Playwright (Microsoft’s browser automation framework) behind the Model Context Protocol. It exposes browser capabilities as MCP tools, letting any AI client control Chromium, Firefox, or WebKit through natural language.

Without Playwright MCP:

1
$ claude "Write an E2E test for the login flow"
2
  → Writes the test code but you need to run it yourself
3
  → You: copy, paste, run, debug, fix selectors...

With Playwright MCP:

1
$ claude "Run an E2E test for the login flow"
2
  → Agent opens a real browser
3
  → Navigates to localhost:3000/login
4
  → Types credentials, clicks submit
5
  → Verifies redirect to dashboard
6
  → Takes screenshot on failure
7
  → Generates the test code from the recorded session

Installation#

1
docker pull mcr.microsoft.com/playwright-mcp/server:latest

1
claude mcp add playwright \
2
  --command docker \
3
  --args "run -i --rm --init -e PLAYWRIGHT_MCP_HEADLESS=true mcr.microsoft.com/playwright-mcp/server"

1
{
2
  "mcpServers": {
3
    "playwright": {
4
      "command": "docker",
5
      "args": [
6
        "run", "-i", "--rm", "--init",
7
        "-e", "PLAYWRIGHT_MCP_HEADLESS=true",
8
        "mcr.microsoft.com/playwright-mcp/server"
9
      ]
10
    }
11
  }
12
}

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

1
claude "Open https://example.com and tell me the page title"
2
  → "The page title is: Example Domain"

Tools Overview#

Playwright MCP exposes a rich set of browser tools:

Real-World Workflows#

1
$ claude "Record an E2E test for the checkout process"
2

3
Agent:
4
  1. Opens browser to localhost:3000
5
  2. Adds product to cart
6
  3. Goes to checkout
7
  4. Fills shipping info
8
  5. Selects payment method
9
  6. Completes purchase
10
  7. Records all actions as Playwright test code
11
  8. Saves: `tests/e2e/checkout.spec.ts`
12

13
→ You get a complete Playwright test without writing a single selector.

1
import { test, expect } from '@playwright/test';
2

3
test('complete checkout flow', async ({ page }) => {
4
  await page.goto('http://localhost:3000');
5
  await page.click('text=Add to Cart');
6
  await page.click('text=Checkout');
7
  await page.fill('[name="email"]', 'test@example.com');
8
  await page.fill('[name="address"]', '123 Main St');
9
  await page.click('text=Place Order');
10
  await expect(page.locator('text=Order Confirmed')).toBeVisible();
11
});

1
$ claude "Check what the new landing page looks like in mobile viewport"
2

3
Agent:
4
  1. Opens browser at 375x812 (iPhone viewport)
5
  2. Navigates to localhost:3000/landing
6
  3. Takes a full-page screenshot
7
  4. Compares with the baseline
8
  5. Reports: "The hero section overlaps with the nav on mobile.
9
     Here's a screenshot showing the issue."
10

11
→ Debug visual bugs without manually resizing your browser.

1
$ claude "Test the signup form with invalid data and verify error messages"
2

3
Agent:
4
  1. Navigates to /signup
5
  2. Submits empty form — verifies "Email is required" error
6
  3. Types invalid email — verifies "Invalid email format" error
7
  4. Types valid email, weak password — verifies password strength indicator
8
  5. Completes full flow with valid data — verifies success redirect
9
  6. Generates comprehensive test suite

1
$ claude "Run the checkout test in Firefox and WebKit too"
2

3
Agent:
4
  1. Opens Chromium → runs checkout flow
5
  2. Opens Firefox → runs checkout flow
6
  3. Opens WebKit → runs checkout flow
7
  4. Compares results: "All three browsers pass.
8
     But Firefox has a 2px layout shift in the payment form."

Playwright MCP vs. Other Browser Tools#

Performance & Token Costs#

Browser automation is inherently expensive in terms of tokens. Each page visit means the agent needs to process the page content, decide what to click, and interpret the result.

Tips to reduce costs:

• Use browser_wait instead of polling
• Take screenshots only when needed
• Reuse page sessions instead of opening new ones
• Limit viewport size to reduce page content token count

Security Considerations#

1. Headless by default: Run in headless mode for CI/CD and production. Use headed mode (HEADLESS=false) only for debugging
2. Port binding: When using Docker, bind to 127.0.0.1 to prevent external access
3. Session isolation: Each Docker container starts fresh. Don’t share user data directories across sessions
4. Rate limiting: Consider using a queue system if running multiple concurrent test suites
5. Never run on production: Playwright MCP is for development and staging environments only

Troubleshooting#

“Browser doesn’t open”

• Did you install browsers? npx playwright install chromium
• Is Docker running? docker ps
• Try non-headless mode: set PLAYWRIGHT_MCP_HEADLESS=false

“Can’t find elements”

• The page might be client-side rendered — add a wait: browser_wait
• Selectors might need adjustment — try using visible text: text=Submit
• The page might have loaded slowly — increase timeouts

“Tests are slow”

• Run in headed mode temporarily to see what’s happening
• Use browser_screenshot to debug element positions
• Reduce viewport size for faster rendering

Summary#

Playwright MCP is the #1 trending MCP server for good reason. It turns natural language descriptions into real browser interactions. For teams writing and maintaining E2E tests, it’s arguably the most impactful MCP server you can install.

The killer combo: Playwright MCP for test generation + GitHub MCP for PR review + Firecrawl MCP for test fixture data.

Series: Practical MCP Servers for Developers — 2026 Edition. Day 4 of 6.