Playwright MCP Server

A Model Context Protocol (MCP) server that provides browser automation capabilities using Playwright with support for dynamic Chrome DevTools Protocol (CDP) endpoints.

Features

• 🌐 Browser Automation: Full Playwright browser automation toolkit (24+ tools)
• 🔗 Dynamic CDP Endpoints: Connect to remote browsers via WebSocket CDP endpoints
• 🚀 Session Management: Proper HTTP session handling with cleanup
• 🛡️ Fallback Support: Automatic fallback to headless browser if CDP fails
• 📦 Easy Integration: Works with any MCP-compatible client
• 🔧 CLI Interface: Command-line interface for easy deployment

Installation

npm install @ejazullah/playwright-mcp-server

Or install globally:

npm install -g @ejazullah/playwright-mcp-server

Package Information

• Package Name: @ejazullah/playwright-mcp-server
• Version: 1.5.0
• Repository: https://github.com/Ejazullah42/playwright-mcp-server
• NPM Registry: https://www.npmjs.com/package/@ejazullah/playwright-mcp-server
• License: MIT
• Node.js: >=18.0.0
• Transport: Both HTTP and stdio supported

Transport Modes

This package supports two transport modes:

HTTP Mode (Default)

• Use case: Claude Desktop, custom HTTP clients
• Command: npx @ejazullah/playwright-mcp-server
• Communication: HTTP server with StreamableHTTP transport
• Port: Configurable (default: 8006)

stdio Mode

• Use case: Supergateway, command-line MCP clients
• Command: npx @ejazullah/playwright-mcp-server --stdio
• Communication: stdin/stdout JSON-RPC
• Port: Not applicable (uses stdio)

Quick Start

Basic Usage

import { PlaywrightMCPServer } from '@ejazullah/playwright-mcp-server';

const server = new PlaywrightMCPServer({
  port: 8005,
  defaultCdpEndpoint: 'wss://your-browser.com/devtools/session-id'
});

await server.start();

CLI Usage

# HTTP mode (default) - starts HTTP server on port 8006
npx @ejazullah/playwright-mcp-server

# stdio mode - for supergateway and MCP clients
npx @ejazullah/playwright-mcp-server --stdio

# Specify custom port (HTTP mode only)
npx @ejazullah/playwright-mcp-server --port 8001

# stdio mode with CDP endpoint
npx @ejazullah/playwright-mcp-server --stdio --cdp-endpoint wss://example.com/devtools/123

# Show help
npx @ejazullah/playwright-mcp-server --help

# Show version
npx @ejazullah/playwright-mcp-server --version

Supergateway Configuration

For supergateway (like in your case), use stdio mode:

Name: playwright
Run script: npx @ejazullah/playwright-mcp-server --stdio
Environment Variables: (none required)

Claude Desktop Configuration

For Claude Desktop and other HTTP-based MCP clients:

Name: playwright
Run script: npx @ejazullah/playwright-mcp-server --port 8001
Environment Variables: (none required)

Example configuration:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@ejazullah/playwright-mcp-server", "--stdio"]
    }
  }
}

Configuration

Server Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | port | number | 8006 | Server port | | defaultCdpEndpoint | string | null | Default CDP WebSocket endpoint |

MCP Client Configuration (HTTP Transport)

For MCP clients using HTTP transport, use this configuration:

{
  "mcpServers": {
    "playwright": {
      "url": "http://localhost:8001/mcp"
    }
  }
}

MCP Client Configuration (Command-based)

For MCP clients that run commands directly:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@ejazullah/playwright-mcp-server", "--port", "8001"]
    }
  }
}

Dynamic CDP Endpoints

Both transport modes support dynamic CDP endpoints:

HTTP Mode

Use URL parameters to specify CDP endpoints per request:

// Connect to specific CDP endpoint
const serverUrl = 'http://localhost:8006/mcp?cdpEndpoint=wss://browser.com/devtools/abc123';
const transport = new StreamableHTTPClientTransport(new URL(serverUrl));

stdio Mode

Pass CDP endpoint as command line argument:

# stdio mode with specific CDP endpoint
npx @ejazullah/playwright-mcp-server --stdio --cdp-endpoint wss://browser.com/devtools/abc123

CDP Endpoint Examples:

• wss://chrome-devtools.example.com/devtools/browser/session-id
• wss://localhost:9222/devtools/browser/abc123
• null or omitted = headless browser (default)

Available Tools

The server provides 24 browser automation tools:

Navigation

• browser_navigate - Navigate to a URL
• browser_navigate_back - Go back to the previous page
• browser_navigate_forward - Go forward to the next page

Page Interaction

• browser_click - Click on elements
• browser_type - Type text into elements
• browser_press_key - Press keyboard keys
• browser_hover - Hover over elements
• browser_drag - Drag and drop elements

Page Analysis

• browser_snapshot - Capture accessibility snapshot
• browser_take_screenshot - Take page screenshots
• browser_evaluate - Execute JavaScript

Form Handling

• browser_select_option - Select dropdown options
• browser_file_upload - Upload files

Tab Management

• browser_tab_new - Open new tabs
• browser_tab_close - Close tabs
• browser_tab_select - Switch between tabs
• browser_tab_list - List open tabs

Utilities

• browser_wait_for - Wait for conditions
• browser_console_messages - Get console logs
• browser_network_requests - Get network requests
• browser_handle_dialog - Handle dialogs
• browser_resize - Resize browser window
• browser_close - Close browser

Examples

Basic Web Scraping (HTTP Mode)

import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
import { Client } from '@modelcontextprotocol/sdk/client/index.js';

const transport = new StreamableHTTPClientTransport(
  new URL('http://localhost:8006/mcp')
);

const client = new Client({
  name: 'web-scraper',
  version: '1.0.0'
}, { capabilities: { tools: {} } });

await client.connect(transport);

// Navigate to page
await client.callTool({
  name: 'browser_navigate',
  arguments: { url: 'https://example.com' }
});

// Take screenshot
await client.callTool({
  name: 'browser_take_screenshot',
  arguments: { filename: 'page.png', fullPage: true }
});

// Get page structure
await client.callTool({
  name: 'browser_snapshot',
  arguments: {}
});

await client.close();

Remote Browser Automation (HTTP Mode)

// Connect to remote browser via CDP
const cdpEndpoint = 'wss://remote-browser.com/devtools/session-123';
const serverUrl = `http://localhost:8006/mcp?cdpEndpoint=${encodeURIComponent(cdpEndpoint)}`;

const transport = new StreamableHTTPClientTransport(new URL(serverUrl));
// ... rest of client code

stdio Mode Usage (for Supergateway)

For supergateway and other stdio-based MCP clients, the server automatically handles browser automation through stdin/stdout communication:

# Start in stdio mode
npx @ejazullah/playwright-mcp-server --stdio

# With specific CDP endpoint
npx @ejazullah/playwright-mcp-server --stdio --cdp-endpoint wss://browser.com/devtools/abc123

API Reference

PlaywrightMCPServer

Constructor

new PlaywrightMCPServer(options)

Methods

• start() - Start the server
• stop() - Stop the server and cleanup
• getStats() - Get server statistics

Development

Setup

git clone https://github.com/Ejazullah42/playwright-mcp-server.git
cd playwright-mcp-server
npm install

Scripts

npm start      # Start the server
npm run dev    # Start with file watching
npm test       # Run tests
npm run lint   # Lint code
npm run format # Format code

Testing

# Start the server in one terminal
npm start

# Run tests in another terminal
npm test

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

Author

Ejazullah - GitHub

License

MIT License - see LICENSE file for details.

Changelog

See CHANGELOG.md for version history.

Support

• 📚 Documentation
• 🐛 Issue Tracker
• 💬 Discussions
• 📦 NPM Package