Automating Real Browser Sessions with Playwright-REPL MCP

Let AI Control Your Real Browser — Not a Throwaway One

The @playwright-repl/mcp server connects AI agents directly to your active Chrome tabs via the Dramaturg extension. Unlike standard browser MCPs that launch clean-slate instances, this system runs Playwright inside the browser’s service worker to maintain session state. This technical shift allows AI to interact with authenticated tools like Gmail or Notion without requiring manual re-login.

Why This Matters

Most browser automation tools rely on isolated ‘throwaway’ instances that lack the user’s cookies, localStorage, and active authentication tokens. This creates a friction-filled developer experience where every automated task requires manual re-authentication or complex session-injection logic, significantly slowing down the feedback loop for AI agents. By utilizing the Chrome Debugger Protocol (CDP) through a browser extension, @playwright-repl/mcp allows the AI to operate side-by-side with the human user. This approach ensures that assertions like expect() run against the actual state of the user’s browser, providing a high-fidelity environment for testing and automation that purely headless or isolated systems cannot replicate.

Key Insights

• The @playwright-repl/mcp package streamlines the 70+ tools found in official Playwright MCPs into just two: run_command and run_script.
• Playwright-crx enables the full Playwright API to execute within the Chrome service worker, bypassing the need for an external Node.js relay.
• The Healer agent identifies broken selectors by taking page snapshots and iterating on code until every line passes verification in the real browser.
• AI agents in this ecosystem are required to execute and verify their scripts before returning output, preventing the ‘hallucinated code’ common in LLM outputs.
• The Dramaturg extension provides a human-AI REPL, allowing users to record interactions as .pw commands or JavaScript code in real-time.

Working Examples

Configuration for Claude Desktop to enable the playwright-repl MCP server.

{"mcpServers": {"playwright-repl": {"command": "playwright-repl-mcp"}}}

Example of standard Playwright API commands executed through the run_script tool.

await page.getByRole('button', { name: 'Sign in' }).click();
await expect(page.getByText('Welcome')).toBeVisible();

Keyword-based .pw syntax supported by the run_command tool for rapid interaction.

snapshot
goto https://example.com
click "Sign in"
fill "Email" "[email protected]"
verify-text "Welcome"

Practical Applications

• Automating data entry in internal enterprise tools where SSO authentication is required. Pitfall: Running the MCP server without the Dramaturg extension active, leading to a WebSocket connection timeout.
• Using the Converter agent to migrate legacy keyword-based automation scripts to idiomatic Playwright JavaScript. Pitfall: Incorrectly assuming the AI can access tabs not focused or explicitly directed via the toolbar dropdown.
• Executing real-time accessibility audits using the ‘snapshot’ command to generate accessibility trees for immediate analysis. Pitfall: Overloading the AI with too many open tabs, which can confuse the tab-targeting logic in the REPL.

References:

• https://dev.to/stevez/let-ai-control-your-real-browser-not-a-throwaway-one-3pma