🎭 Playwright SPA MCP

The Playwright MCP server built for modern web apps — persistent sessions, React/Vue/Angular support, 143+ devices and smart DOM waiting.

Installation · Why · Tools · Examples · Limitations

Overview

An MCP server that drives a real Chromium browser, purpose-built for Single Page Applications. Your assistant can log in, click, type and screenshot — and the SPA's state survives across calls:

You: Log into app.example.com, open the dashboard and screenshot it.

Assistant: (calls spa_session_start, then spa_chain [type-realistic → click → wait-for-idle], then spa_screenshot) Logged in and captured the dashboard — React state preserved across the session.

Why this server?

Installation

# One command — no clone needed
claude mcp add playwright-spa -- npx -y github:manganate006/playwright-spa-mcp

# Install the Chromium browser Playwright drives
npx playwright install chromium

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "playwright-spa": {
      "command": "npx",
      "args": ["-y", "github:manganate006/playwright-spa-mcp"]
    }
  }
}

git clone https://github.com/manganate006/playwright-spa-mcp.git
cd playwright-spa-mcp
npm install
npx playwright install chromium
claude mcp add playwright-spa -- node $(pwd)/src/index.js

Tools

22 tools, spa_ prefix. Chain-action list, 143+ device shortcuts and CLI usage: docs/ADVANCED.md.

Examples

Log into a React app and keep the session — realistic typing fires React's onChange:

spa_session_start({ session: "myapp" })

spa_chain({
  session: "myapp",
  url: "https://app.example.com/login",
  spaMode: "react",
  chain: [
    { action: "type-realistic", selector: "#email", value: "user@example.com" },
    { action: "type-realistic", selector: "#password", value: "secret123" },
    { action: "click", selector: "button[type=submit]" },
    { action: "wait-for-idle" },
    { action: "screenshot" }
  ]
})

// Same session — React state is preserved
spa_click({ session: "myapp", selector: ".dashboard-item" })

Mobile device emulation:

spa_screenshot({ url: "https://example.com", device: "iPhone 15 Pro", fullPage: true })

Authenticated API call reusing the session cookies:

spa_http_request({ session: "myapp", url: "https://api.example.com/user/profile", method: "GET" })

Limitations

• Chromium only — Firefox/WebKit are not wired up; requires npx playwright install chromium

• Local browser — spawns a real browser process; not suited to sandboxes without one

• SPA heuristics — React/Vue/Angular readiness is detected heuristically (spaMode: "auto"); heavy custom frameworks may need explicit wait-for / wait-for-idle

• Sessions are in-memory — they live with the server process and don't persist across restarts

SPA framework support

Detects and waits correctly for React (finishes rendering, proper onChange), Vue (v-model bindings) and Angular (Zone.js stability). Use spaMode: "auto" to detect automatically. Details in docs/ADVANCED.md.

Built with this MCP

License

MIT © manganate006