Browserless MCP Server

A Model Context Protocol (MCP) server for Browserless.io browser automation. This server provides a comprehensive interface to Browserless’s powerful browser automation capabilities through MCP tools.

Features

• PDF Generation: Convert web pages or HTML content to PDF with custom styling
• Screenshots: Capture full-page or element-specific screenshots
• Content Extraction: Get rendered HTML content after JavaScript execution
• Custom Functions: Execute JavaScript code in browser context
• File Downloads: Handle file downloads and programmatic file creation
• Page Export: Export web pages with all resources
• Performance Audits: Run Lighthouse performance audits
• Anti-Detection: Bypass bot detection and anti-scraping measures
• BrowserQL: Execute GraphQL queries for advanced automation
• WebSocket Connections: Create connections for Puppeteer/Playwright
• Health Monitoring: Check instance health and get metrics
• Session Management: Monitor active browser sessions

Installation

1. Clone the repository:

git clone https://github.com/Lizzard-Solutions/browserless-mcp.git
cd browserless-mcp

2. Install dependencies:

npm install

3. Build the project:

npm run build

4. Copy the example environment file:

cp env.example .env

5. Edit .env with your Browserless configuration:

BROWSERLESS_HOST=localhost
BROWSERLESS_PORT=3000
BROWSERLESS_TOKEN=your-secure-token-here
BROWSERLESS_PROTOCOL=http
BROWSERLESS_TIMEOUT=30000
BROWSERLESS_CONCURRENT=5

Usage

Starting the MCP Server

npm start

Or for development:

npm run dev

Using with MCP Clients

The server provides the following tools:

1. Initialize Browserless Connection

{
  "name": "initialize_browserless",
  "arguments": {
    "host": "localhost",
    "port": 3000,
    "token": "your-token",
    "protocol": "http",
    "timeout": 30000,
    "concurrent": 5
  }
}

2. Generate PDF

{
  "name": "generate_pdf",
  "arguments": {
    "url": "https://example.com",
    "options": {
      "format": "A4",
      "printBackground": true,
      "displayHeaderFooter": true,
      "margin": {
        "top": "20mm",
        "bottom": "10mm",
        "left": "10mm",
        "right": "10mm"
      }
    }
  }
}

3. Take Screenshot

{
  "name": "take_screenshot",
  "arguments": {
    "url": "https://example.com",
    "options": {
      "type": "png",
      "fullPage": true,
      "quality": 90
    }
  }
}

4. Extract Content

{
  "name": "get_content",
  "arguments": {
    "url": "https://example.com",
    "waitForSelector": {
      "selector": "#content-loaded",
      "timeout": 5000
    }
  }
}

5. Execute Custom Function

{
  "name": "execute_function",
  "arguments": {