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

Clone the repository:

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

Install dependencies:

npm install

Build the project:

npm run build

Copy the example environment file:

cp env.example .env

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": {
    "code": "export default async function ({ page }) { await page.goto('https://example.com'); const title = await page.title(); return { data: { title }, type: 'application/json' }; }",
    "context": {
      "customData": "value"
    }
  }
}

6. Run Performance Audit

{
  "name": "run_performance_audit",
  "arguments": {
    "url": "https://example.com",
    "config": {
      "extends": "lighthouse:default",
      "settings": {
        "onlyCategories": ["performance", "accessibility"]
      }
    }
  }
}

7. Bypass Bot Detection

{
  "name": "unblock",
  "arguments": {
    "url": "https://protected-site.com",
    "content": true,
    "screenshot": true,
    "stealth": true,
    "blockAds": true
  }
}

8. Execute BrowserQL Query

{
  "name": "execute_browserql",
  "arguments": {
    "query": "mutation { goto(url: \"https://example.com\") { status } click(selector: \"#button\") { success } screenshot { base64 } }",
    "variables": {}
  }
}

9. Create WebSocket Connection

{
  "name": "create_websocket_connection",
  "arguments": {
    "browser": "chromium",
    "library": "puppeteer",
    "stealth": true,
    "viewport": {
      "width": 1920,
      "height": 1080
    }
  }
}

10. Health and Monitoring

{
  "name": "get_health",
  "arguments": {}
}

{
  "name": "get_sessions",
  "arguments": {}
}

{
  "name": "get_metrics",
  "arguments": {}
}

Browserless Setup

Docker Setup

# Basic setup
docker run -p 3000:3000 ghcr.io/browserless/chromium

# With configuration
docker run \
  --rm \
  -p 3000:3000 \
  -e "CONCURRENT=10" \
  -e "TOKEN=your-secure-token" \
  ghcr.io/browserless/chromium

Docker Compose

version: '3.8'

services:
  browserless:
    image: ghcr.io/browserless/chromium:latest
    container_name: browserless
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      - TOKEN=your-secure-token-here
      - CONCURRENT=10
      - TIMEOUT=120000
      - HEALTH=true
      - CORS=true
    volumes:
      - ./data:/app/data
      - ./downloads:/app/downloads

Advanced Examples

Complex Web Scraping

{
  "name": "execute_function",
  "arguments": {
    "code": "export default async function ({ page }) { await page.goto('https://example.com'); await page.waitForSelector('.item'); const items = await page.evaluate(() => Array.from(document.querySelectorAll('.item')).map(el => ({ text: el.textContent, href: el.href }))); return { data: { items }, type: 'application/json' }; }"
  }
}

Multi-step Form Automation

{
  "name": "execute_function",
  "arguments": {
    "code": "export default async function ({ page }) { await page.goto('https://example.com/form'); await page.type('#username', 'user@example.com'); await page.type('#password', 'password123'); await page.click('#submit'); await page.waitForNavigation(); const result = await page.evaluate(() => document.querySelector('.success-message').textContent); return { data: { result }, type: 'application/json' }; }"
  }
}

PDF Report Generation

{
  "name": "generate_pdf",
  "arguments": {
    "html": "<!DOCTYPE html><html><head><style>body{font-family:Arial;margin:20px;} .header{background:#333;color:white;padding:20px;} .content{margin:20px 0;}</style></head><body><div class='header'><h1>Monthly Report</h1></div><div class='content'><h2>Summary</h2><p>This is a generated report with custom styling.</p></div></body></html>",
    "options": {
      "format": "A4",
      "printBackground": true,
      "displayHeaderFooter": true,
      "headerTemplate": "<div style='font-size:12px;'>Confidential Report</div>",
      "footerTemplate": "<div style='font-size:10px;'>Page <span class='pageNumber'></span></div>"
    }
  }
}

Configuration Options

Environment Variables

Variable	Default	Description
`BROWSERLESS_HOST`	`localhost`	Browserless host
`BROWSERLESS_PORT`	`3000`	Browserless port
`BROWSERLESS_TOKEN`	Required	Authentication token
`BROWSERLESS_PROTOCOL`	`http`	Protocol (http/https/ws/wss)
`BROWSERLESS_TIMEOUT`	`30000`	Request timeout in ms
`BROWSERLESS_CONCURRENT`	`5`	Max concurrent sessions

Browserless Configuration

For complete Browserless configuration options, see the Browserless API Reference.

Error Handling

The MCP server provides detailed error messages for common issues:

Connection Errors: Check host, port, and token configuration
Timeout Errors: Increase timeout values for slow-loading pages
Authentication Errors: Verify token is correct and has proper permissions
Resource Errors: Check concurrent session limits and memory usage

Development

Building

npm run build

Testing

npm test

Linting

npm run lint

Formatting

npm run format

Troubleshooting

Common Issues

Connection Refused
- Ensure Browserless is running
- Check host and port configuration
- Verify firewall settings
Authentication Failed
- Verify token is correct
- Check token permissions
- Ensure token is not expired
Timeout Errors
- Increase timeout values
- Check network connectivity
- Monitor Browserless resource usage
Memory Issues
- Reduce concurrent session limit
- Monitor system memory usage
- Restart Browserless instance

Debug Mode

Enable debug logging:

DEBUG=browserless:* npm start

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests
Submit a pull request

License

MIT License - see LICENSE file for details.

Support

For issues and questions:

Check the Browserless API Reference
Review the Browserless Documentation
Open an issue on GitHub

Browserless.io - Browser automation platform
Puppeteer - Node.js library for browser automation
Playwright - Cross-browser automation library
Model Context Protocol - Protocol for AI model interactions

Repository

GitHub: https://github.com/Lizzard-Solutions/browserless-mcp
Issues: https://github.com/Lizzard-Solutions/browserless-mcp/issues
Discussions: https://github.com/Lizzard-Solutions/browserless-mcp/discussions

This server cannot be installed

security - not tested

license - not found

quality - not tested

How are these scores calculated?

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

Enables comprehensive browser automation through Browserless.io including PDF generation, screenshots, content extraction, performance audits, and web scraping with anti-detection capabilities. Provides a complete interface to browser automation tasks through natural language interactions.

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
780
Python
MIT License
Browser Use Server
ztobs
A
security
F
license
A
quality
Enables browser automation using Python scripts, offering operations like taking webpage screenshots, retrieving HTML content, and executing JavaScript.
Last updated -
4
17
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