Metadata-Version: 2.4
Name: browserless-mcp
Version: 0.0.0
Summary: A Model Context Protocol (MCP) server for Browserless.io browser automation
Requires-Python: >=3.11
Requires-Dist: fastmcp>=2.0.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dotenv>=1.0.0
Description-Content-Type: text/markdown

# Browserless MCP Server (Python)

A [FastMCP](https://github.com/jlowin/fastmcp) server that exposes [Browserless.io](https://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](https://docs.astral.sh/uv/) package manager
- A running [Browserless](https://github.com/browserless/browserless) instance

### Start Browserless (Docker)

```bash
# 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

```bash
# 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`:

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

---

## Running

```bash
# 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`):

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

---

## Tool Examples

### Generate PDF

```json
{
  "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

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

### Extract Content

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

### Scrape Structured Data

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

### Execute Custom JS

```json
{
  "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

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

### Bypass Bot Detection

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

### BrowserQL Query

```json
{
  "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