A
securityA
licenseA
qualityFacilitates browser automation with custom capabilities and agent-based interactions, integrated through the browser-use library.
Last updated -
1
838
MIT License
Supports Docker deployment of Browserless instances for scalable browser automation infrastructure
Uses environment configuration files to manage Browserless connection settings and authentication tokens
Hosted on GitHub with issue tracking and community discussions for the MCP server project
Executes BrowserQL GraphQL queries for advanced browser automation workflows and operations
Executes custom JavaScript code in browser contexts for advanced web scraping and automation tasks
Runs Lighthouse performance audits on web pages to analyze performance, accessibility, and other metrics
Built as a Node.js application for browser automation through the Browserless platform
Manages dependencies and provides build scripts for the MCP server installation and development
Creates WebSocket connections for Puppeteer-based browser automation and control
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
.envwith 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 |
|
| Browserless port |
| Required | Authentication token |
|
| Protocol (http/https/ws/wss) |
|
| Request timeout in ms |
|
| 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
Related Projects
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
Related MCP Servers
- AsecurityFlicenseAqualityEnables browser automation using Python scripts, offering operations like taking webpage screenshots, retrieving HTML content, and executing JavaScript.Last updated -420
- -security-license-qualityEnables browser automation and real-time computer vision tasks through AI-driven commands, offering zero-cost digital navigation and interaction for enhanced web experiences.
- -securityFlicense-qualityProvides browser automation capabilities through an API endpoint that interprets natural language commands to perform web tasks using OpenAI's GPT models.Last updated -
Appeared in Searches
- How to replicate or copy website functionality
- Screen sharing or remote desktop access software
- Tool for searching and downloading datasets from Canada's Open Data portal
- MCP server for browser automation, form filling, system login, and website navigation
- Information about scraping tools and techniques