Skip to content
Conduit

mcp server

playwright-mcp-server

A production-ready Java-based Model Context Protocol (MCP) server that bridges LLMs with a live Chromium browser using Playwright Java.

Shoaib7644/playwright-mcp-servercommunitylistedunreviewed
Use tool

Set up

Runs on your computer. Pick your agent and operating system.

This project does not publish an install method we can turn into a config. Follow the README instead.

README

synced Oct 23, 2026

Playwright MCP Server v6

Intelligent Playwright + MCP + BDD Automation Framework Generator

A production-ready Java-based Model Context Protocol (MCP) server that bridges LLMs with a live Chromium browser using Playwright Java.

This framework records real browser interactions, analyzes user intent, generates maintainable BDD automation frameworks, supports intelligent playback with recovery, and exposes atomic browser tools for AI agents.

Table of Contents

  1. Overview
  2. Key Features
  3. Architecture
  4. Core Components
  5. Technology Stack
  6. Prerequisites
  7. Installation & Setup
  8. MCP Integration
  9. Exposed MCP Tools
  10. Smart Wait Engine
  11. Intent Analysis Engine
  12. Intelligent BDD Generation
  13. Generated Framework Structure
  14. UiActions Abstraction Layer
  15. Locator Strategy
  16. Parallel Playback Support
  17. Failure Recovery System
  18. Supported Browser Actions
  19. Environment Variables
  20. Build & Run
  21. Example Workflow
  22. Sample Recording JSON
  23. Troubleshooting Guide
  24. Performance & Design Decisions
  25. Security Considerations
  26. Future Enhancements
  27. Best Practices
  28. FAQ
  29. License

Overview

Playwright MCP Server is an intelligent automation orchestration layer that enables Large Language Models (LLMs) to:

  • Launch and control browsers
  • Record user interactions
  • Replay workflows reliably
  • Generate enterprise-grade BDD frameworks
  • Execute atomic browser operations
  • Analyze raw browser events into business intents
  • Create reusable Page Object Models automatically

The framework is optimized for:

  • AI-assisted QA automation
  • Self-healing browser interactions
  • Intent-driven BDD generation
  • Framework-agnostic automation design
  • Parallel execution
  • Enterprise automation scalability

Key Features

Browser Recording Engine

  • Records clicks, fills, navigations, key presses, uploads, dropdowns, and scrolls
  • Captures semantic locators automatically
  • Supports headed and headless execution
  • CSP bypass support
  • Smart event de-duplication
  • Session-based recording management

Smart Wait Engine (v6)

Automatic synchronization before and after every action:

  • DOM ready checks
  • Network idle detection
  • Element visibility validation
  • Enabled-state verification
  • DOM stabilization logic
  • Action-aware waits

Intent Analyzer

Converts raw DOM events into business-level intents:

Raw EventsDetected Intent
Username + Password + Login ClickLOGIN
Search Fill + EnterSEARCH
Multiple Form Fields + SubmitFORM_SUBMIT
Amount + Transfer ButtonTRANSFER
Upload + ConfirmUPLOAD_FLOW
Dropdown + ConfirmSELECT_FLOW

Intelligent BDD Generator

Automatically generates:

  • Feature files
  • Step definitions
  • Page Objects
  • Runner classes
  • UiActions abstraction layer
  • Playwright implementation layer
  • Scenario Outlines
  • Data-driven examples

Parallel Playback Engine

  • ThreadLocal Playwright sessions
  • Multi-threaded replay
  • Chunk-based event distribution
  • Isolated browser contexts
  • Concurrent execution support

Recovery & Failure Handling

  • Screenshot capture on failure
  • HTML dump generation
  • Automatic DOM re-sync
  • URL validation
  • Retry engine
  • Smart recovery handling

Framework Abstraction Layer

Generated frameworks use:

ui.click(locator);
ui.fill(locator, value);
ui.navigate(url);

This enables future migration to:

  • Selenium
  • Cypress
  • WebDriverIO
  • Appium
  • Any UI engine

without changing Page Objects.

Architecture

┌─────────────────────────────────────────────────────────────┐
│                     MCP HOST / LLM                         │
│        Claude / Cursor / Cline / Custom AI Agent           │
└──────────────────────┬──────────────────────────────────────┘
                       │
                 JSON-RPC over stdio
                       │
┌──────────────────────▼──────────────────────────────────────┐
│                 Playwright MCP Server                      │
│                                                            │
│  ┌──────────────────────────────────────────────────────┐  │
│  │                MCP Tool Layer                       │  │
│  │                                                      │  │
│  │  start_recording                                    │  │
│  │  stop_recording                                     │  │
│  │  playback_recording                                 │  │
│  │  generate_playwright_bdd                            │  │
│  │  execute_atomic_action                              │  │
│  └──────────────────────────────────────────────────────┘  │
│                                                            │
│  ┌──────────────────────────────────────────────────────┐  │
│  │              Intent Analysis Engine                 │  │
│  │                                                      │  │
│  │  LOGIN                                               │  │
│  │  SEARCH                                              │  │
│  │  FORM_SUBMIT                                         │  │
│  │  TRANSFER                                            │  │
│  │  RAW_ACTION                                          │  │
│  └──────────────────────────────────────────────────────┘  │
│                                                            │
│  ┌──────────────────────────────────────────────────────┐  │
│  │              Smart Wait Engine                      │  │
│  │                                                      │  │
│  │  DOM Ready                                           │  │
│  │  Network Idle                                        │  │
│  │  Element Visibility                                  │  │
│  │  Enabled State                                       │  │
│  │  DOM Stabilization                                   │  │
│  └──────────────────────────────────────────────────────┘  │
│                                                            │
│  ┌──────────────────────────────────────────────────────┐  │
│  │              BDD Code Generator                     │  │
│  │                                                      │  │
│  │  Feature Files                                       │  │
│  │  Step Definitions                                    │  │
│  │  Page Objects                                        │  │
│  │  Runners                                              │  │
│  │  UiActions                                            │  │
│  └──────────────────────────────────────────────────────┘  │
└──────────────────────┬──────────────────────────────────────┘
                       │
┌──────────────────────▼──────────────────────────────────────┐
│                  Playwright Java                           │
│                    Chromium Browser                        │
└─────────────────────────────────────────────────────────────┘

Core Components

1. PlaywrightMcpServer.java

Main orchestration engine responsible for:

  • MCP tool registration
  • Browser lifecycle management
  • Event recording
  • Playback execution
  • Smart waits
  • Retry handling
  • Parallel execution
  • Failure recovery
  • Session management

2. IntentAnalyzer.java

Transforms low-level browser events into meaningful business actions.

Supported Intent Types

IntentDescription
LOGINUser authentication flow
SEARCHSearch interaction flow
TRANSFERMonetary/data transfer flow
FORM_SUBMITGeneric form submission
NAVIGATIONURL navigation
SELECT_FLOWDropdown selection flow
UPLOAD_FLOWFile upload flow
RAW_ACTIONUnmatched individual actions

3. BddCodeGenerator.java

Generates complete automation frameworks.

Generated Artifacts

  • Feature files
  • Step definitions
  • Page Objects
  • Runner classes
  • UiActions interface
  • Playwright implementation
  • Data-driven scenarios
  • Assertions
  • Utility methods

Technology Stack

CategoryTechnology
LanguageJava 17+
Build ToolMaven
Browser AutomationPlaywright Java
BDD FrameworkCucumber
MCP ProtocolModel Context Protocol
JSON ProcessingJackson
ReportingAllure + Cucumber Reports
Parallel ExecutionJava Executors + ThreadLocal
BrowserChromium
Loggingjava.util.logging

Prerequisites

ToolVersion
JDK17+
Maven3.9+
Node.jsOptional
OSWindows / Linux / macOS
RAM8 GB Recommended

Installation & Setup

1. Clone Repository

git clone <repository-url>
cd playwright-mcp-server

2. Build Project

mvn clean package -DskipTests

3. Install Playwright Browsers

mvn exec:java@install-browsers

4. Verify Build

Generated JAR:

target/playwright-mcp-server.jar

MCP Integration

Claude Desktop Configuration

macOS

~/Library/Application Support/Claude/claude_desktop_config.json

Windows

%APPDATA%\Claude\claude_desktop_config.json

Example Configuration

{
  "mcpServers": {
    "playwright": {
      "command": "java",
      "args": [
        "-jar",
        "/absolute/path/to/playwright-mcp-server.jar"
      ]
    }
  }
}

Restart Claude Desktop after configuration.

Exposed MCP Tools

1. start_recording

Launches Chromium and starts interaction recording.

Input

{
  "url": "https://example.com",
  "sessionName": "Login Flow",
  "headless": false
}

Features

  • CSP bypass
  • JS injection
  • Browser lifecycle management
  • Event queue setup
  • Session metadata generation

2. stop_recording

Stops recording and returns structured JSON.

Input

{}

Output

  • Raw browser events
  • Structured intents
  • Session metadata
  • Timing data
  • Recording statistics

3. playback_recording

Replays recorded events intelligently.

Input

{
  "jsonRecording": "...",
  "headless": true,
  "parallel": false,
  "threads": 1
}

Features

  • Smart waits
  • Retry engine
  • Recovery logic
  • Parallel execution
  • Failure artifact generation

4. generate_playwright_bdd

Generates complete BDD automation framework.

Input

{
  "jsonRecording": "...",
  "featureName": "User Login",
  "framework": "cucumber",
  "tags": "@smoke @regression"
}

Supported Frameworks

FrameworkRunner
cucumberJUnit 5
testngTestNG
serenitySerenity BDD

Generated Files

FilePurpose
Feature FileGherkin Scenarios
Step DefinitionsStep Implementations
Page ObjectsUI Layer
RunnerTest Execution
UiActionsAbstraction Layer
PlaywrightUiActionsPlaywright Implementation

5. execute_atomic_action

Executes single Playwright actions.

Example

{
  "action": "fill",
  "selector": "placeholder:Search",
  "value": "Playwright"
}

Supported Actions

ActionDescription
navigateNavigate to URL
clickClick element
fillFill input
typeType text
clearClear field
pressPress keyboard key
hoverHover element
checkCheck checkbox
uncheckUncheck checkbox
select_optionSelect dropdown option
upload_fileUpload file
screenshotCapture screenshot
get_textExtract text
is_visibleVisibility validation
get_htmlExtract HTML
waitExplicit wait
scrollScroll page

Smart Wait Engine

The Smart Wait Engine automatically stabilizes browser state.

Wait Strategy

ActionPre-WaitPost-Wait
CLICKVisibleLoad + Network Idle
FILLVisible + EnabledStable DOM
NAVIGATEDOM ReadyNetwork Idle
SELECT_OPTIONVisibleStable DOM
CHECKVisibleStable DOM
UPLOAD_FILEAttachedStable DOM

Benefits

  • Reduces flaky tests
  • Removes hard-coded waits
  • Stabilizes asynchronous pages
  • Improves replay reliability

Intent Analysis Engine

The Intent Analyzer converts low-level browser actions into business workflows.

Example

Raw Events

FILL username
FILL password
CLICK login

Generated Intent

LOGIN(username, password)

Generated Gherkin

When user logs in with "john" and "<password>"

Intelligent BDD Generation

The generator creates enterprise-ready automation frameworks.

Generated Feature Example

@smoke @regression
Feature: User Login

  Background:
    Given the browser is open

  Scenario: User Login
    When user logs in with "john" and "<password>"

Generated Page Object Example

public class LoginPage {

    private final UiActions ui;

    private final String USERNAME_FIELD = "#username";
    private final String PASSWORD_FIELD = "#password";

    public LoginPage login(String username, String password) {
        ui.fill(USERNAME_FIELD, username);
        ui.fill(PASSWORD_FIELD, password);
        return this;
    }
}

Generated Framework Structure

generated-project/
│
├── pom.xml
│
├── src/
│   ├── main/
│   │   └── java/com/qa/
│   │       ├── actions/
│   │       │   ├── UiActions.java
│   │       │   └── PlaywrightUiActions.java
│   │       │
│   │       └── pages/
│   │           └── UserLoginPage.java
│   │
│   └── test/
│       ├── java/com/qa/
│       │   ├── runners/
│       │   │   └── UserLoginRunner.java
│       │   │
│       │   └── stepdefs/
│       │       └── UserLoginSteps.java
│       │
│       └── resources/
│           ├── features/
│           │   └── UserLogin.feature
│           │
│           └── TestData/
│               └── testdata.properties

UiActions Abstraction Layer

Purpose

Decouples Page Objects from Playwright.

Benefits

  • Framework independence
  • Easy migration
  • Cleaner architecture
  • Better maintainability
  • Improved scalability

Example

public interface UiActions {
    void click(String selector);
    void fill(String selector, String value);
    void navigate(String url);
}

Locator Strategy

The framework prioritizes resilient semantic locators.

Priority Order

PriorityLocator
1href
2id
3data-testid
4role
5placeholder
6label
7text
8CSS
9nth fallback

Examples

role:button:Login
placeholder:Search
label:Email
testid:submit-btn

Parallel Playback Support

Features

  • Multi-threaded execution
  • Thread-isolated browser sessions
  • Chunk-based replay
  • ThreadLocal Playwright instances

Example

{
  "parallel": true,
  "threads": 4
}

Failure Recovery System

On action failure the framework:

  1. Captures screenshot
  2. Dumps HTML
  3. Logs failure details
  4. Validates URL
  5. Attempts DOM re-sync
  6. Continues execution where possible

Failure Artifact Directory

./mcp-failures/

Generated artifacts:

failure.png
failure.html
failure.log

Environment Variables

VariableDefaultPurpose
MCP_RETRY_MAX3Retry attempts
MCP_TIMEOUT_MS30000Timeout configuration
MCP_RETRY_DELAY_MS800Retry delay
MCP_MAX_STEP_DELAY_MS500Playback pacing
MCP_FAILURE_DIR./mcp-failuresFailure artifacts
MCP_LOG_LEVELINFOLogging level

Build & Run

Package Project

mvn clean package

Run Server

java -jar target/playwright-mcp-server.jar

Run Generated Framework

mvn test

Run Specific Tags

mvn test -Dcucumber.filter.tags="@smoke"

Example Workflow

Step 1 — Start Recording

{
  "url": "https://example.com"
}

Step 2 — Perform Browser Actions

  • Login
  • Search
  • Submit forms
  • Upload files

Step 3 — Stop Recording

{}

Step 4 — Generate Framework

{
  "featureName": "User Login"
}

Step 5 — Execute Tests

mvn test

Sample Recording JSON

{
  "schemaVersion": "6.0.0",
  "sessionName": "Login Test",
  "status": "COMPLETED",
  "events": [
    {
      "actionType": "FILL",
      "selector": "#username",
      "inputValue": "john"
    },
    {
      "actionType": "CLICK",
      "selector": "#login"
    }
  ],
  "intents": [
    {
      "intentType": "LOGIN",
      "description": "User login"
    }
  ]
}

Troubleshooting Guide

ProblemSolution
Browser executable not foundRun Playwright browser installation
MCP host disconnectsEnsure logs go to STDERR only
Events not capturedVerify CSP bypass
Playback failuresIncrease timeout values
Parallel replay instabilityReduce thread count
Elements not foundVerify selector strategy
Flaky playbackEnable Smart Wait defaults
Headless issuesRun in headed mode
Permissions issuesVerify OS browser permissions
Chromium crashesIncrease system memory

Browser Installation

mvn exec:java@install-browsers

Debug Logging

export MCP_LOG_LEVEL=DEBUG

Performance & Design Decisions

Design ChoiceReason
ThreadLocal PlaywrightSafe parallel execution
Smart waitsReduce flaky automation
Intent-based generationHuman-readable BDD
UiActions abstractionFramework independence
Retry engineReliability improvement
CSP bypassCapture events from restricted apps
Semantic locatorsBetter selector stability
Structured recoveryNon-destructive replay

Security Considerations

  • CSP bypass is enabled intentionally for automation recording
  • Sensitive passwords are masked during intent generation
  • Browser contexts are isolated
  • Failure artifacts may contain sensitive information
  • Generated frameworks should not commit secrets

Future Enhancements

Planned improvements:

  • Selenium UiActions implementation
  • Firefox and WebKit support
  • AI-powered self-healing selectors
  • Visual validation engine
  • API testing integration
  • Test impact analysis
  • Cloud execution support
  • Docker support
  • Kubernetes scaling
  • CI/CD templates
  • Reporting dashboard

Best Practices

Recommended

  • Use semantic locators
  • Prefer role/testid selectors
  • Keep generated frameworks version controlled
  • Store secrets externally
  • Run parallel execution carefully
  • Use Scenario Outlines for test data

Avoid

  • Hard-coded waits
  • Absolute XPath selectors
  • Sharing browser contexts across threads
  • Storing credentials in source code

FAQ

Does this support headless execution?

Yes.

Can generated frameworks run independently?

Yes. Generated projects are standalone Maven automation frameworks.

Does this support parallel execution?

Yes.

Can Selenium be plugged in later?

Yes. The UiActions abstraction was specifically designed for this.

Does the framework support retries?

Yes. Playback includes retry and recovery logic.

Can I generate data-driven frameworks?

Yes. Scenario Outline generation is supported.

License

This project is intended for educational, enterprise automation, and AI-assisted testing use cases.

Please add your preferred license:

  • MIT
  • Apache 2.0
  • Proprietary Enterprise License

Final Notes

Playwright MCP Server v6 is designed as an AI-native automation framework generation platform.

It combines:

  • Playwright browser automation
  • MCP protocol tooling
  • Intent analysis
  • Smart synchronization
  • Enterprise BDD generation
  • Parallel execution
  • Recovery-aware replay

into a single extensible architecture.

The result is a scalable foundation for AI-assisted QA automation systems, autonomous browser agents, and intelligent framework generation pipelines.

↑↓ navigate openesc close