<div align="center">

🎭 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

</div>

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?

Feature	playwright-spa-mcp	Other Playwright MCPs
Persistent sessions	✅	❌
React/Vue/Angular detection	✅	❌
Smart DOM idle waiting	✅	❌
Realistic typing	✅	❌
Device emulation	143+	Limited
Action chains	✅	❌
HTTP with browser cookies	✅	❌

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"]
    }
  }
}

<details> <summary>Alternative: clone & install locally</summary>

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

</details>

Tools

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

Group	Tools
📸 Screenshot & navigation	spa_screenshot, spa_navigate, spa_go_back, spa_go_forward, spa_wait_idle
📝 Interactions	spa_click, spa_fill, spa_type_realistic, spa_upload, spa_drag
⛓️ Chains	spa_chain (run many actions in one call)
🔐 Sessions	spa_session_start, spa_session_end, spa_session_list
🔎 Inspection	spa_get_text, spa_assert, spa_evaluate, spa_http_request
🖼️ iframes	spa_iframe_click, spa_iframe_fill
ℹ️ Discovery	spa_list_devices, spa_list_actions

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

Project	Description
atp.mangi.fr	🎾 ATP tennis stats since 1968
piscinade.com	🏊 Pool-party finder in France

License

MIT © manganate006