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.

Overview
Key Features
Architecture
Core Components
Technology Stack
Prerequisites
Installation & Setup
MCP Integration
Exposed MCP Tools
Smart Wait Engine
Intent Analysis Engine
Intelligent BDD Generation
Generated Framework Structure
UiActions Abstraction Layer
Locator Strategy
Parallel Playback Support
Failure Recovery System
Supported Browser Actions
Environment Variables
Build & Run
Example Workflow
Sample Recording JSON
Troubleshooting Guide
Performance & Design Decisions
Security Considerations
Future Enhancements
Best Practices
FAQ
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 Events	Detected Intent
Username + Password + Login Click	LOGIN
Search Fill + Enter	SEARCH
Multiple Form Fields + Submit	FORM_SUBMIT
Amount + Transfer Button	TRANSFER
Upload + Confirm	UPLOAD_FLOW
Dropdown + Confirm	SELECT_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

Intent	Description
LOGIN	User authentication flow
SEARCH	Search interaction flow
TRANSFER	Monetary/data transfer flow
FORM_SUBMIT	Generic form submission
NAVIGATION	URL navigation
SELECT_FLOW	Dropdown selection flow
UPLOAD_FLOW	File upload flow
RAW_ACTION	Unmatched 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

Category	Technology
Language	Java 17+
Build Tool	Maven
Browser Automation	Playwright Java
BDD Framework	Cucumber
MCP Protocol	Model Context Protocol
JSON Processing	Jackson
Reporting	Allure + Cucumber Reports
Parallel Execution	Java Executors + ThreadLocal
Browser	Chromium
Logging	java.util.logging

Prerequisites

Tool	Version
JDK	17+
Maven	3.9+
Node.js	Optional
OS	Windows / Linux / macOS
RAM	8 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

Framework	Runner
cucumber	JUnit 5
testng	TestNG
serenity	Serenity BDD

Generated Files

File	Purpose
Feature File	Gherkin Scenarios
Step Definitions	Step Implementations
Page Objects	UI Layer
Runner	Test Execution
UiActions	Abstraction Layer
PlaywrightUiActions	Playwright Implementation

5. execute_atomic_action

Executes single Playwright actions.

Example

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

Supported Actions

Action	Description
navigate	Navigate to URL
click	Click element
fill	Fill input
type	Type text
clear	Clear field
press	Press keyboard key
hover	Hover element
check	Check checkbox
uncheck	Uncheck checkbox
select_option	Select dropdown option
upload_file	Upload file
screenshot	Capture screenshot
get_text	Extract text
is_visible	Visibility validation
get_html	Extract HTML
wait	Explicit wait
scroll	Scroll page

Smart Wait Engine

The Smart Wait Engine automatically stabilizes browser state.

Wait Strategy

Action	Pre-Wait	Post-Wait
CLICK	Visible	Load + Network Idle
FILL	Visible + Enabled	Stable DOM
NAVIGATE	DOM Ready	Network Idle
SELECT_OPTION	Visible	Stable DOM
CHECK	Visible	Stable DOM
UPLOAD_FILE	Attached	Stable 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

Priority	Locator
1	href
2	id
3	data-testid
4	role
5	placeholder
6	label
7	text
8	CSS
9	nth 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:

Captures screenshot
Dumps HTML
Logs failure details
Validates URL
Attempts DOM re-sync
Continues execution where possible

Failure Artifact Directory

./mcp-failures/

Generated artifacts:

failure.png
failure.html
failure.log

Environment Variables

Variable	Default	Purpose
MCP_RETRY_MAX	3	Retry attempts
MCP_TIMEOUT_MS	30000	Timeout configuration
MCP_RETRY_DELAY_MS	800	Retry delay
MCP_MAX_STEP_DELAY_MS	500	Playback pacing
MCP_FAILURE_DIR	./mcp-failures	Failure artifacts
MCP_LOG_LEVEL	INFO	Logging 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

Problem	Solution
Browser executable not found	Run Playwright browser installation
MCP host disconnects	Ensure logs go to STDERR only
Events not captured	Verify CSP bypass
Playback failures	Increase timeout values
Parallel replay instability	Reduce thread count
Elements not found	Verify selector strategy
Flaky playback	Enable Smart Wait defaults
Headless issues	Run in headed mode
Permissions issues	Verify OS browser permissions
Chromium crashes	Increase system memory

Browser Installation

mvn exec:java@install-browsers

Debug Logging

export MCP_LOG_LEVEL=DEBUG

Performance & Design Decisions

Design Choice	Reason
ThreadLocal Playwright	Safe parallel execution
Smart waits	Reduce flaky automation
Intent-based generation	Human-readable BDD
UiActions abstraction	Framework independence
Retry engine	Reliability improvement
CSP bypass	Capture events from restricted apps
Semantic locators	Better selector stability
Structured recovery	Non-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

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.

Name		Name	Last commit message	Last commit date
Latest commit History 7 Commits
src/main		src/main
target		target
.DS_Store		.DS_Store
.gitignore		.gitignore
LICENSE		LICENSE
Readme.md		Readme.md
copilot-instructions.md		copilot-instructions.md
mcp-config.json		mcp-config.json
playwright_mcp_intellij_guide.html		playwright_mcp_intellij_guide.html
pom.xml		pom.xml

Folders and files

Latest commit

History

Repository files navigation

Playwright MCP Server v6

Intelligent Playwright + MCP + BDD Automation Framework Generator

Table of Contents

Overview

Key Features

Browser Recording Engine

Smart Wait Engine (v6)

Intent Analyzer

Intelligent BDD Generator

Parallel Playback Engine

Recovery & Failure Handling

Framework Abstraction Layer

Architecture

Core Components

1. PlaywrightMcpServer.java

2. IntentAnalyzer.java

Supported Intent Types

3. BddCodeGenerator.java

Generated Artifacts

Technology Stack

Prerequisites

Installation & Setup

1. Clone Repository

2. Build Project

3. Install Playwright Browsers

4. Verify Build

MCP Integration

Claude Desktop Configuration

macOS

Windows

Example Configuration

Exposed MCP Tools

1. start_recording

Input

Features

2. stop_recording

Input

Output

3. playback_recording

Input

Features

4. generate_playwright_bdd

Input

Supported Frameworks

Generated Files

5. execute_atomic_action

Example

Supported Actions

Smart Wait Engine

Wait Strategy

Benefits

Intent Analysis Engine

Example

Raw Events

Generated Intent

Generated Gherkin

Intelligent BDD Generation

Generated Feature Example

Generated Page Object Example

Generated Framework Structure

UiActions Abstraction Layer

Purpose

Benefits

Example

Locator Strategy

Priority Order

Examples

Parallel Playback Support

Features

Example

Failure Recovery System

Failure Artifact Directory

Environment Variables

Build & Run

Package Project

Run Server