@zibby/mcp-browser

Wrapper for @playwright/mcp with stable ID support and event recording.

Features

• ✅ Injects stable IDs via --init-script for reliable element targeting
• ✅ Records browser events to events.json with stable IDs
• ✅ Video recording with accurate timestamp synchronization
• ✅ Passes through all official Playwright MCP functionality

Installation

npm install @zibby/mcp-browser

Usage

As MCP Server

Add to your MCP configuration:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@zibby/mcp-browser"]
    }
  }
}

Command Line

# Basic usage (same as @playwright/mcp)
npx @zibby/mcp-browser

# With headless mode
npx @zibby/mcp-browser --headless

# With custom output directory
npx @zibby/mcp-browser --output-dir ./recordings

How It Works

This package wraps the official @playwright/mcp and adds:

1. Stable ID Injection: Automatically injects stable element IDs into the page
2. Event Recording: Records all browser interactions with stable IDs
3. Video Sync: Synchronizes event timestamps with video recordings

Event Recording

Events are recorded to events.json in the session directory:

[
  {
    "id": 0,
    "type": "navigate",
    "timestamp": "2026-03-05T12:00:00.000Z",
    "videoOffsetMs": 0,
    "videoOffsetFormatted": "00:00:00.000",
    "data": {
      "url": "https://example.com"
    }
  },
  {
    "id": 1,
    "type": "click",
    "timestamp": "2026-03-05T12:00:02.500Z",
    "videoOffsetMs": 2500,
    "videoOffsetFormatted": "00:00:02.500",
    "data": {
      "element": "Login button",
      "stableId": "zibby-login-btn-a1b2c3"
    }
  }
]

Configuration

Set the session path via environment variable:

export ZIBBY_SESSION_INFO=/path/to/.session-info.json

Remote / sidecar browser (pluggable runtime)

By default the wrapper launches a local Chromium (the official @playwright/mcp behavior). If you set BROWSER_WS_ENDPOINT to a remote Chrome's CDP/WS endpoint, it instead connects to that browser over CDP (connectOverCDP) and launches no local Chromium — so a browser agent can run on a slim image with no baked browser binary, pointing at a HOSTED Chrome (browserless / Browserbase / any CDP endpoint). On a Zibby self-host box the platform's own browser is the on-demand browser sidecar deployed from the marketplace, reached over MCP — this knob is only for bringing your own hosted Chrome.

# Connect to a hosted Chrome over CDP (no local Chromium needed):
export BROWSER_WS_ENDPOINT='wss://chrome.browserless.io?token=...'
npx @zibby/mcp-browser

Implemented by reusing @playwright/mcp's native --cdp-endpoint flag (which takes precedence over local launch). Aliases BROWSER_CDP_ENDPOINT and PLAYWRIGHT_WS_ENDPOINT are also accepted. Unset → unchanged (launch local).

Compatibility

• Node.js >= 18.0.0
• Compatible with all @playwright/mcp features
• Works with Playwright >= 1.49.0

License

Proprietary — Copyright (c) 2026 Zibby Labs. All rights reserved. Unauthorized copying, distribution, or use is prohibited.

Related Packages

• @zibby/cli - Command-line interface
• @zibby/test-automation-core - Core automation engine
• @zibby/mcp-jira - Jira MCP server