@freelw/playwright-mcp-wrapper

A wrapper for @playwright/mcp that handles CDP endpoint acquisition from cloud platform for Cursor MCP integration.

Overview

This package serves as a bridge between Cursor's MCP (Model Context Protocol) system and Playwright MCP. It automatically acquires a CDP (Chrome DevTools Protocol) endpoint from your cloud platform using your project ID and API key, then launches Playwright MCP with the acquired endpoint.

Installation

npm install @freelw/playwright-mcp-wrapper

Usage in Cursor

Add this to your Cursor MCP configuration:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@freelw/playwright-mcp-wrapper@latest",
        "--project-id=your-project-id",
        "--api-key=your-api-key"
      ]
    }
  }
}

Command Line Usage

You can also run it directly:

npx @freelw/playwright-mcp-wrapper --project-id=your-project-id --api-key=your-api-key

Configuration

Required Parameters (choose one)

Option 1: Using Cloud Platform

• --project-id: Your project ID for the cloud platform
• --api-key: Your API key for authentication

Option 2: Using Direct CDP Endpoint

• --cdp-endpoint: Direct CDP endpoint URL (e.g., wss://example.com/devtools/browser/123)

Optional Parameters

• --timeout-action: Action timeout in milliseconds (default: 15000ms)
• --timeout-navigation: Navigation timeout in milliseconds (default: 15000ms)
• --clear-all: Close all existing pages before starting (requires CDP endpoint to be available)

Examples

Using project ID and API key:

npx @freelw/playwright-mcp-wrapper --project-id=test_project_123 --api-key=test_api_key_456

Using direct CDP endpoint:

npx @freelw/playwright-mcp-wrapper --cdp-endpoint=wss://browser.example.com/devtools/browser/123

Clear all existing pages before starting:

# With CDP endpoint
npx @freelw/playwright-mcp-wrapper --cdp-endpoint=wss://... --clear-all

# With project ID and API key
npx @freelw/playwright-mcp-wrapper --project-id=xxx --api-key=xxx --clear-all

How it Works

1. The wrapper receives your project ID and API key
2. It calls the cloud platform API to create a browser session
3. It retrieves the WebSocket CDP endpoint from the session
4. It launches @playwright/mcp with the acquired CDP endpoint
5. Cursor can now interact with Playwright through the MCP protocol

API Endpoints

The wrapper uses the following cloud platform API endpoints:

• POST /instance - Create a new browser session
• GET /json/version?session_id=<id> - Get WebSocket debugger URL
• GET /health - Health check
• GET /logs/<session_id> - Get session logs
• DELETE /instance?session_id=<id> - Delete session

Environment Variables

You can optionally set the following environment variables:

• WS_PREFIX - WebSocket URL prefix (default: wss://freelw.cc)
• MCP_DEBUG - Enable debug logging (set to true or 1 to enable)

Debug Logging

When MCP_DEBUG is enabled, all stdin/stdout/stderr communications with the Playwright process will be logged to:

~/.playwright-mcp/logs/mcp-debug-{timestamp}.log

To enable debug logging in Cursor, add the environment variable to your MCP configuration:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@freelw/playwright-mcp-wrapper@latest",
        "--project-id=your-project-id",
        "--api-key=your-api-key"
      ],
      "env": {
        "MCP_DEBUG": "true"
      }
    }
  }
}

Or when running from command line:

MCP_DEBUG=true npx @freelw/playwright-mcp-wrapper --project-id=xxx --api-key=xxx

Development

Prerequisites

• Node.js 16+
• TypeScript

Build

npm run build

Development Mode

npm run dev

License

MIT