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

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

License

MIT