Puppeteer and Playwright MCP

You spent an hour implementing a new checkout flow. The code looks right, the types check, the unit tests pass. But when you open the browser, the submit button is hidden behind a sticky footer. Your AI could have caught this in seconds — if it could see the browser.

What You’ll Walk Away With

• Setup for Playwright MCP and Puppeteer MCP across all three tools
• Understanding of accessibility-tree mode versus screenshot mode
• Copy-paste prompts for E2E testing, visual regression, and web scraping
• Strategies for running browser MCP in CI/CD

Playwright MCP: The Recommended Choice

Microsoft’s official Playwright MCP uses structured accessibility trees by default. The AI understands page elements semantically — buttons by their label, inputs by their name — rather than through expensive vision calls.

Cursor

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

Claude Code

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

Codex

[mcp.playwright]
transport = "stdio"
command = "npx"
args = ["-y", "@playwright/mcp@latest"]

Key tools: browser_navigate, browser_click, browser_fill, browser_screenshot, browser_get_text, browser_select, and browser_evaluate.

Tip

Copy-paste prompt for E2E testing:

“Open localhost:3000/register, fill in the form with test@example.com and a secure password, submit it, and verify the success message appears. Then navigate to /login, log in with the same credentials, and confirm the dashboard loads. Take a screenshot of the dashboard.”

Puppeteer MCP: The Alternative

The Puppeteer MCP server is a lighter-weight option for Chrome-only automation and quick scraping tasks.

Cursor

{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-puppeteer"]
    }
  }
}

Claude Code

{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-puppeteer"]
    }
  }
}

Codex

[mcp.puppeteer]
transport = "stdio"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-puppeteer"]

Choose Playwright for cross-browser support and accessibility-tree interaction. Choose Puppeteer for Chrome-specific features or simpler scraping tasks.

Accessibility Tree vs. Screenshots

Accessibility tree mode (default) — Fast, token-efficient, reliable. Buttons identified by label, inputs by name. Use for all standard interactions.

Vision mode — Takes screenshots for visual understanding. Necessary for canvas apps, complex visualizations, or when the accessibility tree misrepresents the UI.

Note

Start with accessibility tree mode. Only switch to vision mode when the AI cannot find an element it knows should exist. Canvas elements, iframes, and shadow DOM components sometimes require vision mode.

Tip

Copy-paste prompt for visual regression testing:

“Navigate to localhost:3000/pricing, take a full-page screenshot. Toggle dark mode using the header switch, take another screenshot. Compare the two and flag any elements with broken layout or poor contrast in dark mode.”

Tip

Copy-paste prompt for web scraping:

“Navigate to https://example.com/pricing. Extract all plan names, prices, and feature lists. Structure the data as a JSON array with one object per plan. Do not interact with login forms or cookie banners.”

When This Breaks

Browser fails to launch. Run npx playwright install chromium to download the browser binary. On CI servers, install system dependencies with npx playwright install-deps.

AI clicks the wrong element. Multiple elements share the same accessible name. Add aria-label attributes or instruct the AI to use the element index in the accessibility tree.

Screenshots are blank. The browser session starts fresh without authentication. Navigate to the login page first, or configure stored cookies.

Timeouts on slow pages. Default navigation timeout is 30 seconds. For SSR pages, increase it: “Navigate to the page and wait up to 60 seconds for full load.”

What’s Next

Database MCP Servers Connect your AI to SQL and NoSQL databases.

Documentation Context Keep your AI grounded in current library documentation.