Browserless MCP Server (Python)

A FastMCP server that exposes Browserless.io browser-automation capabilities as MCP tools. Built in Python with uv, fastmcp, and httpx.

---

Features

Tool	Description
browserless_generate_pdf	Convert a URL or HTML to PDF
browserless_take_screenshot	Capture full-page or clipped screenshots
browserless_get_content	Extract fully-rendered HTML after JS execution
browserless_execute_function	Run arbitrary JS inside a real browser
browserless_scrape	Extract structured data via CSS selectors
browserless_run_performance_audit	Lighthouse performance/accessibility audit
browserless_unblock	Bypass bot detection / anti-scraping measures
browserless_execute_browserql	Run BrowserQL GraphQL automation queries
browserless_get_websocket_url	Build WebSocket URL for Puppeteer/Playwright
browserless_get_health	Check Browserless instance health
browserless_get_sessions	List active browser sessions
browserless_get_metrics	Get instance performance metrics
browserless_configure_connection	Update connection settings at runtime

---

Prerequisites

• Python ≥ 3.11
• uv package manager
• A running Browserless instance

Start Browserless (Docker)

# Quick start (no auth)
docker run -p 3000:3000 ghcr.io/browserless/chromium

# With token
docker run -p 3000:3000 \
  -e TOKEN=my-secret-token \
  -e CONCURRENT=10 \
  ghcr.io/browserless/chromium

---

Installation

# Clone
git clone https://github.com/your-org/browserless-mcp-python.git
cd browserless-mcp-python

# Install dependencies with uv
uv sync

# Copy and edit config
cp .env.example .env

Edit .env:

BROWSERLESS_HOST=localhost
BROWSERLESS_PORT=3000
BROWSERLESS_TOKEN=my-secret-token
BROWSERLESS_PROTOCOL=http
BROWSERLESS_TIMEOUT=30000
BROWSERLESS_CONCURRENT=5

---

Running

# Via uv
uv run browserless-mcp

# Or directly
uv run python src/browserless_mcp/server.py

# Or after installing
pip install -e .
browserless-mcp

---

Claude Desktop Configuration

Add to ~/.config/claude/claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "browserless": {
      "command": "uvx",
      "args": ["browserless-mcp"],
      "env": {
        "BROWSERLESS_HOST": "localhost",
        "BROWSERLESS_PORT": "3000",
        "BROWSERLESS_TOKEN": "your-token"
      }
    }
  }
}

---

Tool Examples

Generate PDF

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

Take Screenshot

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

Extract Content

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

Scrape Structured Data

{
  "name": "browserless_scrape",
  "arguments": {
    "url": "https://news.ycombinator.com",
    "elements": [
      { "selector": ".titleline > a" },
      { "selector": ".score" }
    ]
  }
}

Execute Custom JS

{
  "name": "browserless_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' }; }"
  }
}

Performance Audit

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

Bypass Bot Detection

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

BrowserQL Query

{
  "name": "browserless_execute_browserql",
  "arguments": {
    "query": "mutation { goto(url: \"https://example.com\") { status } screenshot { base64 } }"
  }
}

---

Project Structure

browserless-mcp-python/
├── src/
│   └── browserless_mcp/
│       ├── __init__.py       # Package metadata
│       ├── config.py         # Env-based configuration
│       ├── client.py         # Shared httpx HTTP helpers
│       └── server.py         # FastMCP server + all tools
├── .env.example              # Example environment config
├── pyproject.toml            # uv/hatch build config
└── README.md

---

Environment Variables

Variable	Default	Description
BROWSERLESS_HOST	localhost	Browserless host
BROWSERLESS_PORT	3000	Browserless port
BROWSERLESS_TOKEN	(empty)	Auth token (required for secured instances)
BROWSERLESS_PROTOCOL	http	http, https, ws, or wss
BROWSERLESS_TIMEOUT	30000	Request timeout in milliseconds
BROWSERLESS_CONCURRENT	5	Max concurrent sessions (informational)

---

License

MIT