EasyPlaywrightMCP

LLM-driven Playwright MCP for automated testing and demo videos.

Capture: synthetic cursor + always-on click highlight, 1920×1080 @ deviceScaleFactor 2, WebM→H.264 60fps minterpolate, smooth rAF scroll.
Narration: Microsoft Edge neural TTS via edge-tts.

Install

Client	Guide
Cursor	docs/INSTALL-CURSOR.md
Cursor CLI	docs/INSTALL-CURSOR-CLI.md
Claude Desktop	docs/INSTALL-CLAUDE.md
Claude CLI	docs/INSTALL-CLAUDE-CLI.md

Example prompts

Using EasyPlaywrightMCP Make a demo video of the feature in my last PR

Using EasyPlaywrightMCP Connect my google oauth and test this feature in production. Report the success or failure reason for each operation

Using EasyPlaywrightMCP Create a demo video of the steps in this MD

Workflows

Automated testing

login → save profileId (or set_session_auth for Google/bot-blocked OAuth)
start_session (usually headless) with profileId
Loop: query_session → orchestrate_session
end_session
Short answer to the user (pass/fail + findings)

Demo videos

login if auth is needed (or set_session_auth for restricted providers)
start_session with recordVideoPath (demoMode / auto-narrate on by default)
Loop: query_session → orchestrate_session — put spoken lines in description / narration; server TTS + holds
end_session (finalizes WebM, trims idle, writes/updates .cues.json)
compile_demo with clip videoPath only (loads cues automatically)

Demo vs testing: Recording sessions conjoin speech and UI on the server. Testing sessions (no recordVideoPath) keep snappy startMs/endMs pacing.

Restricted auth: For Google OAuth / Sign in with Google (and Microsoft, Discord, Cloudflare bot walls, etc.), do not use headed login. Immediately give the user the login URL, Network → Cookie header steps, and the console snippet from MCP instructions; then set_session_auth with their paste → start_session({ profileId }).

Per-app cookie guides: LinkedIn · Google OAuth / Workspace

Tools & type examples

`login`

// LoginInput
{
  siteUrl: "https://app.example.com",
  authUrl: "https://app.example.com/login",
  username?: "user@example.com",
  password?: "secret",
  oauth?: {
    accessToken?: "eyJ...",
    cookies?: [{ name: "sid", value: "x", domain: "app.example.com" }],
    localStorage?: [{ name: "token", value: "eyJ..." }]
  },
  httpCredentials?: { username: "u", password: "p" },
  tokens?: { bearer?: "eyJ...", cookies?: [], localStorage?: [] },
  timeoutMs?: 120000,
  profileId?: "prof_abc" // reuse
}
// LoginResult → { ok: true, profileId: "prof_…", strategy: "password" }

Strategies: password · http_basic · token_inject · oauth_tokens · manual (headed OAuth/password window) · reuse_profile

`set_session_auth`

// SetSessionAuthInput
{
  siteUrl: "https://app.example.com/dashboard",
  credentialsJson: JSON.stringify({
    origin: "https://app.example.com",
    cookies: [{ name: "session", value: "abc", domain: "app.example.com", path: "/" }],
    localStorage: [{ name: "token", value: "eyJ..." }],
    sessionStorage: []
  }),
  sessionId?: "sess_…", // optional: also inject into a live session
  authUrl?: "https://app.example.com/login"
}
// → { ok: true, profileId: "prof_…", strategy: "restricted_auth", sessionId?: "sess_…" }

Use when the user must log in in their own browser. Always (Google OAuth / Sign in with Google, Microsoft, Apple, Discord, Cloudflare Turnstile, Okta/Auth0 social). Accepts Network Cookie-header snippet JSON or Playwright storageState. Always saves a reusable profileId.

`start_session`

{
  startUrl?: "https://app.example.com/dashboard",
  headed?: false,
  recordVideoPath?: "C:/Videos/clip.webm", // omit = no record; set => demoMode
  narrate?: true, // default true when recording; false = silent capture
  voice?: "en-US-AndrewNeural",
  rate?: "+10%",
  profileId?: "prof_abc"
}
// → { sessionId: "sess_…", headed: false, recording: true, demoMode: true, startUrl?: "…" }

`query_sessions` / `query_session`

// query_session
{ sessionId: "sess_…" }
// → { url, title, viewport, ariaSnapshot, interactive: [{ role, name, selectorHint, inputType? }] }

`orchestrate_session`

{
  sessionId: "sess_…",
  recordStepsPath?: "C:/Videos/steps.md",
  commands: [
    {
      action: "click", // move|click|tap|type|press|scroll|wait|navigate|select|hover|upload
      description: "Open Settings from the sidebar", // also default VO text in demoMode
      narration?: "Spoken override",
      skipNarration?: false,
      startMs: 0, // ignored for pacing while recording
      endMs: 1000,
      selector: "nav >> text=Settings",
      speed: "fast", // fast (default) | slow | timed
      fill?: false, // demos: false for live typing
      files?: ["C:/path/to/file.pdf"], // upload action
      useFileChooser?: false // upload: click + FileChooser instead of setInputFiles
    }
  ]
}
// → { commands: [{ index, description, action, startMs, endMs, videoStartMs?, videoEndMs?, ok, reason? }] }
// Recording also writes C:/Videos/clip.cues.json

`end_session`

{ sessionId: "sess_…" }
// → { ok: true, videoPath?: "C:/Videos/clip.webm" }

`compile_demo`

{
  outputPath: "C:/Videos/final-demo.mp4",
  fast?: false, // skip minterpolate for quick check
  content: [
    {
      kind: "slate",
      eyebrow: "INTRO",
      heading: "Product Demo",
      body: "A quick walkthrough",
      durationMs: 3000,
      narration: [{ startMs: 0, endMs: 2800, text: "Welcome to the demo." }]
    },
    {
      kind: "clip",
      videoPath: "C:/Videos/clip.webm" // loads clip.cues.json automatically
    }
  ]
}
// → { ok: true, outputPath: "C:/Videos/final-demo.mp4" }

Prerequisites

Node 20+
ffmpeg / ffprobe on PATH (Gyan build: winget install Gyan.FFmpeg)
python -m pip install edge-tts
Chromium via npx playwright install chromium (runs on npm install)

Install

Hey Siri, install https://github.com/Macioa/EasyPlaywrightMCP to cursor

Client	Doc
Cursor IDE	docs/INSTALL-CURSOR.md
Cursor CLI	docs/INSTALL-CURSOR-CLI.md
Claude Desktop	docs/INSTALL-CLAUDE.md
Claude Code CLI	docs/INSTALL-CLAUDE-CLI.md

npm install
npm run build
npm start   # stdio MCP
npm test
npm run typecheck

Auth profiles and scratch files live under %USERPROFILE%\.easy-playwright-mcp\.