# Browserless MCP server

> Enables AI agents to perform web scraping, browser automation, site crawling, and Lighthouse performance audits via the Browserless API.

- Repository: https://github.com/browserless/browserless-mcp
- Page: https://hostedmcp.org/servers/browserless/browserless-mcp
- Transport: stdio, remote
- Stars: 19
- Latest version: 1.48.0

## Install

### Claude Code

```sh
claude mcp add --env 'BROWSERLESS_TOKEN=<YOUR_BROWSERLESS_TOKEN>' browserless-mcp -- npx -y @browserless.io/mcp
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "browserless-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@browserless.io/mcp"
      ],
      "env": {
        "BROWSERLESS_TOKEN": "<YOUR_BROWSERLESS_TOKEN>"
      }
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "browserless-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@browserless.io/mcp"
      ],
      "env": {
        "BROWSERLESS_TOKEN": "<YOUR_BROWSERLESS_TOKEN>"
      }
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"browserless-mcp","type":"stdio","command":"npx","args":["-y","@browserless.io/mcp"],"env":{"BROWSERLESS_TOKEN":"<YOUR_BROWSERLESS_TOKEN>"}}'
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "browserless-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@browserless.io/mcp"
      ],
      "env": {
        "BROWSERLESS_TOKEN": "<YOUR_BROWSERLESS_TOKEN>"
      }
    }
  }
}
```

### Codex

```sh
codex mcp add browserless-mcp --env 'BROWSERLESS_TOKEN=<YOUR_BROWSERLESS_TOKEN>' -- npx -y @browserless.io/mcp
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.browserless-mcp]
command = "npx"
args = ["-y", "@browserless.io/mcp"]

[mcp_servers.browserless-mcp.env]
BROWSERLESS_TOKEN = "<YOUR_BROWSERLESS_TOKEN>"
```

### Gemini CLI

```sh
gemini mcp add -s user -e 'BROWSERLESS_TOKEN=<YOUR_BROWSERLESS_TOKEN>' browserless-mcp npx -- -y @browserless.io/mcp
```

### Gemini settings.json (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "browserless-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@browserless.io/mcp"
      ],
      "env": {
        "BROWSERLESS_TOKEN": "<YOUR_BROWSERLESS_TOKEN>"
      }
    }
  }
}
```

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `BROWSERLESS_TOKEN` | yes | yes | Your Browserless API token |
| `BROWSERLESS_API_URL` | no | no | Browserless API endpoint (regional or self-hosted) |
| `BROWSERLESS_PUBLIC_URL` | no | no |  |

## Tools (15)

- `browserless_smartscraper`
- `browserless_search`
- `browserless_map`
- `browserless_crawl`
- `browserless_performance`
- `browserless_function`
- `browserless_export`
- `browserless_agent`
- `browserless_skill`
- `browserless_profiles`
- `browserless_account`
- `browserless_usage`
- `browserless_sessions`
- `browserless_show`
- `browserless_logs`

## FAQ

### Can the server handle JavaScript-heavy websites?

Yes, the smart scraper tool automatically handles JavaScript-heavy pages and anti-bot measures.

### What can I do with the browserless_agent tool?

It allows you to drive a persistent browser session using a ReAct loop, supporting multi-tab workflows, screenshots, and captcha solving.

### How long do Lighthouse report files last?

Files expire after 15 minutes or when the MCP session ends.