Browserless MCP Server

MCP (Model Context Protocol) server for Browserless.io — expose the Browserless smart scraper API to LLM clients like Claude Desktop, Cursor, VS Code, and Windsurf.

Quick Start

Get an API token from browserless.io (free tier available), then point your MCP client at the hosted server:

{
  "mcpServers": {
    "browserless": {
      "url": "https://mcp.browserless.io/mcp?token=your-token-here"
    }
  }
}

No local install — see Configuration for per-client snippets.

Tools

Tool	Description
browserless_smartscraper	Scrape any webpage using cascading strategies (HTTP fetch, proxy, headless browser, captcha solving). Returns content in requested formats: markdown, html, screenshot, pdf, links.
browserless_search	Search the web using Browserless and optionally scrape each result. Supports web, news, and image search with geo-targeting and time filters.
browserless_map	Discover and map all URLs on a website. Crawls via sitemaps and link extraction. Returns URLs with optional titles and descriptions. Useful for site audits and content discovery.
browserless_crawl	Crawl a website and scrape every discovered page. Supports depth control, path filtering, sitemap strategies, and configurable scrape options. Returns scraped content and metadata for each page.
browserless_performance	Run Lighthouse audits on any URL. Returns scores and metrics for accessibility, best practices, performance, PWA, and SEO. Optionally filter by category or supply performance budgets.
browserless_function	Execute custom Puppeteer JavaScript on the Browserless cloud. The function receives a page object and optional context; return { data, type } to control the payload and Content-Type.
browserless_download	Run custom Puppeteer code and return the file Chrome downloads during execution (e.g. after clicking a download link). The downloaded file is streamed back to the caller.
browserless_export	Export a webpage via the Browserless /export API. Fetches the URL and returns its native content (HTML, PDF, image, etc.) with automatic content-type detection.
browserless_agent	Drive a persistent browser session via a ReAct loop: snapshot the page, plan, batch interactions (click, type, scroll, evaluate, etc.), and re-snapshot. Uses ref-based selectors derived from snapshots, supports multi-tab workflows, screenshots, captcha solving, and live URLs.
browserless_skill	Load an on-demand recipe for a non-trivial page mechanic (shadow DOM, cookie consent, modals, captchas, dynamic content, snapshot misses, screenshots, tabs). Companion to browserless_agent.

Skills

The server ships with a built-in library of Skills — on-demand recipes the agent can load to handle tricky page mechanics. Skills auto-inject into browserless_agent responses when their triggers fire (e.g. the agent hits a cookie banner), and can also be loaded manually via the browserless_skill tool.

Skill	Source	Purpose
shadow-dom	src/skills/shadow-dom.md	Deep selectors and iframe targeting through shadow roots.
cookie-consent	src/skills/cookie-consent.md	Vendor-specific dismiss recipes (OneTrust, Cookiebot, Didomi, TrustArc, etc.).
modals	src/skills/modals.md	Closing dialogs, alertdialogs, and overlay close-button heuristics.
captchas	src/skills/captchas.md	Using the solve command, response semantics, and escalation paths (Cloud only).
dynamic-content	src/skills/dynamic-content.md	Choosing the right wait* method for async/AJAX/SPA content.
snapshot-misses	src/skills/snapshot-misses.md	Handling truncated/empty snapshots and image-rendered content.
screenshots	src/skills/screenshots.md	When to screenshot vs. snapshot, scope and format choices.
tabs	src/skills/tabs.md	Multi-tab workflows and peek-without-switching via targetId.

Load a skill explicitly:

{
  "method": "tools/call",
  "params": {
    "name": "browserless_skill",
    "arguments": { "id": "cookie-consent" },
  },
}

Residential proxy (browserless_agent)

Pass a top-level proxy object on browserless_agent to route the session through residential IPs. Use this when targets IP-block datacenter traffic.

{
  "method": "tools/call",
  "params": {
    "name": "browserless_agent",
    "arguments": {
      "method": "goto",
      "params": { "url": "https://example.com" },
      "proxy": {
        "proxy": "residential",
        "proxyCountry": "us",
        "proxySticky": true,
      },
    },
  },
}

Field	Notes
proxy	"residential" — only value supported today.
proxyCountry	ISO-2 country code ("us", "de"). Auto-normalized to lowercase. Non-letter values are rejected.
proxyState	US state name with whitespace replaced by underscores ("new_york"). Paid-plan gated — non-eligible tokens get a 401.
proxyCity	City target. Paid/enterprise plan gated — non-eligible tokens get a 401.
proxySticky	Stable IP while the underlying WebSocket stays open. Reconnects (idle drop, network blip, browser crash) allocate a new sticky id and new IP.
proxyLocaleMatch	Match navigator locale to the proxy IP country.
proxyPreset	Named preset (e.g. "px_amazon01"). Available presets are plan-dependent — ask Browserless support for your list.
externalProxyServer	Bring-your-own upstream, e.g. http://user:pass@host:port. Must be http:// or https://.

Note: proxyCountry / proxyState / proxyCity / proxySticky / proxyLocaleMatch / proxyPreset require either proxy: "residential" or externalProxyServer to be set. The MCP rejects this combination at validation time; without it, the API would silently ignore them.

The proxy object is read once at session creation. To change it, call close and start a new session — the agent client keys sessions on the proxy fingerprint, so passing a different config will land on a fresh WebSocket.

Configuration

The server is hosted at https://mcp.browserless.io/mcp. Authenticate via headers (preferred) or a ?token= query parameter.

Using headers (recommended for clients that support them):

{
  "mcpServers": {
    "browserless": {
      "url": "https://mcp.browserless.io/mcp",
      "headers": {
        "Authorization": "Bearer your-token-here"
      }
    }
  }
}

Using URL query parameters (for clients like Claude.ai custom connectors that only accept a URL):

https://mcp.browserless.io/mcp?token=your-token-here

To connect to a specific Browserless regional endpoint, add the x-browserless-api-url header or the browserlessUrl query parameter:

{
  "mcpServers": {
    "browserless": {
      "url": "https://mcp.browserless.io/mcp",
      "headers": {
        "Authorization": "Bearer your-token-here",
        "x-browserless-api-url": "https://production-lon.browserless.io"
      }
    }
  }
}

https://mcp.browserless.io/mcp?token=your-token-here&browserlessUrl=https://production-lon.browserless.io

When both headers and query parameters are present, headers take precedence.

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "browserless": {
      "url": "https://mcp.browserless.io/mcp?token=your-token-here"
    }
  }
}

Cursor

Add to your Cursor MCP settings:

{
  "mcpServers": {
    "browserless": {
      "url": "https://mcp.browserless.io/mcp?token=your-token-here"
    }
  }
}

VS Code

Add to your VS Code settings (settings.json):

{
  "mcp": {
    "servers": {
      "browserless": {
        "url": "https://mcp.browserless.io/mcp",
        "headers": {
          "Authorization": "Bearer your-token-here"
        }
      }
    }
  }
}

Windsurf

Add to your Windsurf MCP configuration:

{
  "mcpServers": {
    "browserless": {
      "url": "https://mcp.browserless.io/mcp?token=your-token-here"
    }
  }
}

Self-Hosting

The server can also be run locally — useful for air-gapped deployments or pointing at a self-hosted Browserless instance. Clone this repo and build the Docker image:

docker build -f docker/Dockerfile -t browserless-mcp .

docker run \
  -e BROWSERLESS_TOKEN=your-token \
  -e BROWSERLESS_API_URL=https://your-browserless-instance.example.com \
  -p 8080:8080 \
  browserless-mcp

Then point your MCP client at http://localhost:8080/mcp using the same header/query-parameter auth as above.

Self-hosted environment variables

Variable	Required	Default	Description
BROWSERLESS_TOKEN	Yes	—	Your Browserless API token
BROWSERLESS_API_URL	No	https://production-sfo.browserless.io	API endpoint (for self-hosted Browserless)
TRANSPORT	No	stdio	Transport type: stdio or httpStream
PORT	No	8080	HTTP server port (only for httpStream transport)
BROWSERLESS_TIMEOUT	No	30000	Request timeout in milliseconds
BROWSERLESS_MAX_RETRIES	No	3	Max retry attempts for failed requests
BROWSERLESS_CACHE_TTL	No	60000	Cache TTL in milliseconds (0 to disable)

MCP Resources

Resource URI	Description
browserless://api-docs	Smart scraper API documentation
browserless://status	Live service health status

MCP Prompts

Prompt	Description
scrape-url	Scrape a webpage and summarize its content
extract-content	Extract specific information from a webpage

Development

npm install
npm run build
npm test
npm run coverage

Tests

The test suite uses Mocha with Chai and Sinon. Specs live alongside the code in test/ (test/lib/, test/tools/, test/prompts/, test/resources/, test/integration/) and run against the compiled output in build/.

• npm test — compiles TypeScript and runs every *.spec.js under build/test/. No external services or BROWSERLESS_TOKEN are required; the API client is stubbed.
• npm run coverage — runs the suite under c8 with the thresholds configured in package.json (lines ≥ 80%, branches ≥ 70%, functions ≥ 80%).

Tests run automatically on every pull request via the Test workflow on Node 24. PRs must keep the suite green before they can merge.

API Token

Get your API token at browserless.io. The token authenticates all requests to the Browserless API.

License

SSPL-1.0