Better Playwright MCP

better-playwright-mcp

A better Playwright MCP (Model Context Protocol) server that uses a client-server architecture for browser automation.

Why Better?

Traditional browser automation tools send entire page HTML to AI assistants, which quickly exhausts token limits and makes complex web interactions impractical. better-playwright-mcp solves this with an innovative semantic snapshot algorithm that reduces page content by up to 90% while preserving all meaningful elements.

The Problem

Full page HTML often exceeds 100K+ tokens
Most HTML is noise: inline styles, tracking scripts, invisible elements
AI assistants have limited context windows (even with 200K limits)
Complex web automation becomes impossible after just a few page loads

Our Solution: Semantic Snapshots

Our core innovation is a multi-stage pruning algorithm that:

Identifies meaningful elements - Interactive elements (buttons, inputs), semantic HTML5 tags, and text-containing elements
Generates unique identifiers - Each element gets a hash-based xp attribute derived from its XPath for precise targeting
Removes invisible content - Elements with display:none, zero dimensions, or hidden parents are marked and removed
Unwraps useless wrappers - Eliminates divs and spans that only wrap other elements
Strips unnecessary attributes - Keeps only essential attributes like href, value, placeholder

Result: A clean, semantic representation that typically uses only 10% of the original tokens while maintaining full functionality.

Architecture

This project implements a unique two-tier architecture:

MCP Server - Communicates with AI assistants via Model Context Protocol
HTTP Server - Runs in the background to control the actual browser instances

AI Assistant <--[MCP Protocol]--> MCP Server <--[HTTP]--> HTTP Server <---> Browser

This design allows the MCP server to remain lightweight while delegating browser control to a dedicated HTTP service.

Features

🎯 90% token reduction through semantic HTML snapshots
🎭 Full Playwright browser automation via MCP
🏗️ Client-server architecture for better separation of concerns
🛡️ Stealth mode to avoid detection
📍 Hash-based element identifiers for precise targeting
💾 Persistent browser profiles
🚀 Optimized for long-running automation tasks
📊 Token-aware output with automatic truncation

Installation

npm install -g better-playwright-mcp

Usage

Default Mode (MCP)

The MCP server requires an HTTP server to be running. You need to start both:

Step 1: Start the HTTP server

npx better-playwright-mcp server

Step 2: In another terminal, start the MCP server

npx better-playwright-mcp

The MCP server will:

Start listening on stdio for MCP protocol messages
Connect to the HTTP server on port 3102
Route browser automation commands through the HTTP server

Options:

--snapshot-dir <path> - Directory to save snapshots

Standalone HTTP Server Mode

You can also run the HTTP server independently (useful for debugging or custom integrations):

npx better-playwright-mcp server

Options:

-p, --port <number> - Server port (default: 3102)
--host <string> - Server host (default: localhost)
--headless - Run browser in headless mode
--chromium - Use Chromium instead of Chrome
--no-user-profile - Do not use persistent user profile
--user-data-dir <path> - User data directory
--snapshot-dir <path> - Directory to save snapshots

MCP Tools

When used with AI assistants, the following tools are available:

Page Management

createPage - Create a new browser page with name and description
activatePage - Activate a specific page by ID
closePage - Close a specific page
listPages - List all managed pages with titles and URLs
closeAllPages - Close all managed pages
listPagesWithoutId - List unmanaged browser pages
closePagesWithoutId - Close all unmanaged pages
closePageByIndex - Close page by index

Browser Actions

browserClick - Click an element using its xp identifier
browserType - Type text into an element
browserHover - Hover over an element
browserSelectOption - Select options in a dropdown
browserPressKey - Press keyboard keys
browserFileUpload - Upload files to file input
browserHandleDialog - Handle browser dialogs (alert, confirm, prompt)
browserNavigate - Navigate to a URL
browserNavigateBack - Go back to previous page
browserNavigateForward - Go forward to next page
scrollToBottom - Scroll to bottom of page/element
scrollToTop - Scroll to top of page/element
waitForTimeout - Wait for specified milliseconds
waitForSelector - Wait for element to appear

Snapshot & Utilities

getPageSnapshot - Get semantic HTML snapshot with xp identifiers
getScreenshot - Take a screenshot (PNG/JPEG)
getPDFSnapshot - Generate PDF of the page
getElementHTML - Get HTML of specific element
downloadImage - Download image from URL
captureSnapshot - Capture full page with automatic scrolling

How It Works

Semantic Snapshots in Action

Before (original HTML):

<div class="wrapper" style="padding: 20px; margin: 10px;">
  <div class="container">
    <div class="inner">
      <button class="btn btn-primary" onclick="handleClick()" 
              style="background: blue; color: white;">
        Click me
      </button>
    </div>
  </div>
</div>

After (semantic snapshot):

button xp=3fa2b8c1 Click me

The algorithm:

Removes unnecessary wrapper divs
Strips inline styles and event handlers
Adds unique identifier (xp attribute) - a hash of the element's XPath
Preserves only meaningful content

Diff-Based Optimization

To reduce data transfer and token usage:

First snapshot is always complete
Subsequent snapshots only include changes (diffs)
Automatic caching for performance

Stealth Features

Browser instances are configured with:

Custom user agent strings
Disabled automation indicators
WebGL vendor spoofing
Canvas fingerprint protection

Examples

Creating and Navigating Pages

// MCP Tool Usage
{
  "tool": "createPage",
  "arguments": {
    "name": "shopping",
    "description": "Amazon shopping page",
    "url": "https://amazon.com"
  }
}

// Returns: { pageId: "uuid", snapshot: "..." }

Interacting with Elements

// Click on element using its xp identifier
{
  "tool": "browserClick",
  "arguments": {
    "pageId": "uuid",
    "ref": "3fa2b8c1"  // The xp attribute value from snapshot
  }
}

// Type text into input field
{
  "tool": "browserType",
  "arguments": {
    "pageId": "uuid",
    "ref": "xp456",
    "text": "search query",
    "submit": true  // Press Enter after typing
  }
}

Capturing Page State

// Get semantic snapshot
{
  "tool": "getPageSnapshot",
  "arguments": {
    "pageId": "uuid"
  }
}

// Take screenshot
{
  "tool": "getScreenshot",
  "arguments": {
    "pageId": "uuid",
    "fullPage": true,
    "type": "png"
  }
}

Development

Prerequisites

Node.js >= 18.0.0
TypeScript
Chrome or Chromium browser

Building from Source

# Clone the repository
git clone https://github.com/yourusername/better-playwright-mcp.git
cd better-playwright-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode
npm run dev

Project Structure

better-playwright-mcp/
├── src/
│   ├── index.ts                 # MCP mode entry point
│   ├── server.ts                # HTTP server mode entry point
│   ├── playwright-mcp.ts        # MCP server implementation
│   ├── client/
│   │   └── playwright-client.ts # HTTP client for MCP→HTTP communication
│   ├── server/
│   │   └── playwright-server.ts # HTTP server controlling browsers
│   ├── extractor/
│   │   ├── parse2.ts           # HTML parsing with xp identifier generation
│   │   ├── simplify-html.ts    # HTML simplification
│   │   └── utils.ts            # Extraction utilities
│   └── utils/
│       └── token-limiter.ts    # Token counting and limiting
├── bin/
│   └── cli.js                  # CLI entry point
├── package.json
├── tsconfig.json
├── CLAUDE.md                   # Instructions for AI assistants
└── README.md

Troubleshooting

Common Issues

MCP server not connecting
- Ensure the HTTP server is accessible on port 3102
- Check firewall settings
- Try running with DEBUG=* npx better-playwright-mcp
Browser not launching
- Ensure Chrome or Chromium is installed
- Try using --chromium flag
- Check system resources
Token limit exceeded
- Snapshots are automatically truncated to 20,000 tokens
- Use targeted selectors to reduce snapshot size
- Consider using screenshot instead of snapshot for visual inspection

Debug Mode

Enable detailed logging:

DEBUG=* npx better-playwright-mcp

Logs and Records

Operation records are saved to:

macOS/Linux: /tmp/playwright-records/
Windows: %TEMP%\playwright-records\

Each page has its own directory with timestamped operation logs.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT

Install Server

HTTP connection URL

security – no known vulnerabilities

license - not found

quality - confirmed to work

How are these scores calculated?

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

Tools

View all tools

A client-server browser automation solution that reduces HTML token usage by up to 90% through semantic snapshots, enabling complex web interactions without exhausting AI context windows.

Related MCP Servers

Browser-Use MCP Server
Saik0s
A
security
A
license
A
quality
Facilitates browser automation with custom capabilities and agent-based interactions, integrated through the browser-use library.
Last updated -
1
775
Python
MIT License
MCP Browser Use Server
JovaniPink
A
security
F
license
A
quality
Enables AI agents to interact with web browsers using natural language, featuring automated browsing, form filling, vision-based element detection, and structured JSON responses for systematic browser control.
Last updated -
1
50
Python
Deepseek R1 MCP Server
grapheneaffiliate
-
security
A
license
-
quality
Enables browser automation and real-time computer vision tasks through AI-driven commands, offering zero-cost digital navigation and interaction for enhanced web experiences.
Last updated -
0
1
JavaScript
MIT License
MCP Server
jonnyhoff
-
security
F
license
-
quality
Provides browser automation capabilities through an API endpoint that interprets natural language commands to perform web tasks using OpenAI's GPT models.
Last updated -
Python

View all related MCP servers