Skip to main content
Glama

Browserless MCP Server

MCP Badge

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.

Migrating from legacy SSE

Remote connections use Streamable HTTP at /mcp. The legacy GET /sse and POST /messages endpoints return 404, including in self-hosted TRANSPORT=httpStream installs. Update your client's server URL to /mcp and use Authorization: Bearer <token> for authentication. For clients that store server bindings or credentials remotely, update those resources as well. Streamable HTTP still uses SSE for streaming responses; /mcp streaming and stdio connections remain supported.

Authenticated artifact saving

On the full hosted surface, initialize a connection with the non-secret header x-browserless-artifact-delivery: mcp-resource to request metadata-only saved-file results. Omission preserves legacy HTTP guidance. Later requests may omit the header and inherit the session preference; reconnect to change it. This is a routing preference, not authorization or client capability negotiation. Local stdio is unchanged. Release the corresponding plugin opt-in only after deploying a compatible server and passing an authenticated hosted smoke test.

Save-mode results identify a browserless-download://<id>/<encoded-filename> resource and its filename, MIME type, decoded byte count and expiry. Explicit resources/read returns a binary blob, including for saved JSON; it never returns saved content as text. The short browserless-download://<id> upload handle remains distinct. Both MCP reads and existing GET /download/:id require authentication and token-derived ownership; knowing a URI does not authorize access. The first authorized consumption wins across both routes. Files expire after 15 minutes or earlier session cleanup. A failed delivery after consumption cannot be retried or automatically regenerated.

Client profile

Saving without binary payload in model requests

Claude Code 2.1.327 Linux CLI, explicit ReadMcpResourceTool

Deterministic-model probes verified disk serialization for PDF, ZIP, PNG, saved JSON, empty files, Unicode/percent filenames, 1 MiB and 10 MiB payloads. This does not verify real-model fallback behavior.

Claude Code 2.1.327 macOS CLI

Operator-reported real-model revalidation: three headless denied-copy runs stopped with no Read call, base64 or token in transcripts; two approved controls saved a byte-exact 1 MiB file and a valid PNG, with zero Read calls.

Claude Code CLI 2.1.327 or newer on Linux/macOS

Plugin prerequisite, not blanket certification: requires an explicit reader known to return only saved-file metadata, plus copy approval. Unknown or inline handling is unsupported.

Claude Desktop or other MCP clients

Not verified. The resource protocol alone does not guarantee context-free saving. Refuse this path until the client's handling has been tested.

Copying blobSavedTo from Claude Code's sensitive ~/.claude directory requires permission approval. Check existence and byte count through filesystem metadata only. If approval is denied or unavailable, stop and report the failure; never use Read, cat, an image viewer or other content inspection of the source or destination as a save fallback. These instructions are not a client-enforced security boundary.

Real-model follow-up with the revised skill text explicitly loaded, Claude Code 2.1.327 Linux CLI and Sonnet 4.6: three denied-copy runs stopped without content inspection, and three explicitly approved controls copied the exact 98,530-byte PNG. No image payload appeared in 21 captured model requests. The old instructions also stopped safely on Linux, so Linux did not reproduce the reported macOS failure; the subsequent operator-reported macOS revalidation is summarized above. The Linux evaluation tests loaded instructions, not automatic skill discovery or a deployed endpoint.

The native route enforces a conservative 10 MiB decoded maximum before consumption. Claude Code rejects SSE events larger than 16 MB; the 50 MiB store ceiling is not a native-client transfer guarantee. Artifacts above 10 MiB may still be stored up to the 50 MiB ceiling until the 15-minute expiry or earlier session cleanup, but their native descriptors deliberately expose no URI or handle: saving and reuse are unsupported from those results. A previously known identifier remains subject to owner authentication and the HTTP 50 MiB limit; the native result is not an HTTP recovery path. Native results do not suggest local credential reads, shell-authentication fallbacks or inline payloads. New local-file uploads are unsupported in native HTTP mode while native staging is disabled; an existing unconsumed handle can still be reused. Client-side saved files, transcripts and diagnostics have their own retention; absence from model requests is not absence from the user's disk.

In native sessions, export/function binary results and smart-scraper attachments default to saving. toDisk: true also saves function/export JSON or text; smart-scraper requested text remains text. toDisk: false explicitly requests inline analysis and can expose the payload to the model. Legacy/stdio omission retains existing output. Agent screenshots retain their explicit params.toDisk: true selection. The restricted connector does not expose binary artifact resources or the new save parameters.

Replay playback is not a save-only operation: without an MCP Apps view, players at or below the existing inline limit still return HTML containing recording data in the tool result, including in native sessions. That content can enter model requests. Only saved replay files use metadata-only native descriptors; the delivery header does not make inline playback context-free.

Related MCP server: Pinchtab MCP Wrapper

Tools

Tool

Description

browserless_smartscraper

Scrape a single webpage and return its content as markdown or HTML, or AI-extracted JSON and summaries. Handles JavaScript-heavy pages and anti-bot measures automatically. For content across multiple pages, use browserless_crawl; to list a site's URLs, use browserless_map.

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. Scans 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 category scores inline and saves the full JSON report outside the conversation: a local path (stdio) or authenticated single-use download URL (HTTP). Download to disk and inspect only needed fields with jq; files expire after 15 minutes or when the MCP session ends. Optionally filter by category, emulate a mobile or desktop device, supply a custom Lighthouse config, or supply performance budgets.

browserless_function

Execute custom Puppeteer JavaScript on the Browserless cloud. The function receives a page object and optional context; return bytes (e.g. await page.screenshot()) directly for an image or file, a string for text, or any other value for JSON text.

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, live URLs, and file upload/download (captured downloads auto-surface as handles; bytes never enter context).

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.

browserless_profiles

List the authentication profiles saved for the current token, with cookie and origin counts. Pass a profile's name as profile to another tool to reuse its logged-in state.

browserless_account

Read the account behind the current token: plan, unit balance, billing period, and API key names. Never returns API token values.

browserless_usage

Read request and unit consumption: successes, errors, timeouts, queueing, peak concurrency, captchas, proxy bytes and units. Optionally scoped to specific API keys.

browserless_sessions

Inspect active/persistent sessions, recordings, and integrations. action: "replay" prepares a recording and offline player. On the full surface, MCP Apps clients also receive a viewRef for browserless_show.

browserless_show

Display an owned, previously prepared session replay, screenshot gallery, or recorded video inline. Full surface only; never repeats the capture, recording download, or browser operation.

browserless_logs

Read Browserless's own record of recent requests: what was attempted, whether it failed, why it stopped, how long it took and what it cost. The tool for diagnosing a run that failed on the Browserless side. Available window is plan-dependent.

Inline session replay

On the full surface, an MCP Apps client uses two calls:

browserless_sessions({ action: "replay", sessionId: "<recorded-session>" })
// Returns a compact summary, viewRef, expiresAt, and offline-player instructions.
browserless_show({ viewRef: "<returned-view-reference>" })
// Renders the prepared replay inline; does not repeat the recording download.

The player starts paused and includes play/pause, a keyboard-accessible timeline, rewind, playback speed, skip-inactive, and fullscreen where the host permits it. Controls follow the host's light/dark theme; the recorded page retains its own appearance. UI scripts, styles, and rrweb are bundled, with no runtime CDN. External assets referenced by recordings are blocked by the widget's CSP; embedded assets remain available.

Replay events travel in widget-only metadata. Complete results above 2 MiB use browserless_view_data, an app-only reader with bounded gzip/identity pages (128 KiB maximum reply, 50 MiB maximum decoded recording). This reader does not render a widget and should never be called by the model to inspect raw events.

References are owned by the authenticated caller/account and API scope, expire after 15 minutes, and survive MCP transport reconnects. Every show/read rechecks source access; deleted recordings and revoked API keys fail closed. OAuth follows the server's existing verification-cache policy. Loading/retries never extend the deadline. Keep the original offline-player fallback if a view expires. Clients without MCP Apps retain the existing replay output.

Snapshots are bounded and process-local. Deploy with routing that keeps prepared views on the owning process; shared view storage is required for arbitrary cross-worker reads. Restart or eviction makes a view unavailable and never reruns the original operation. Replay presentation tools/resources are absent from the compliant surface, whose existing tool list is unchanged.

Inline request-log explorer

On the full surface, MCP Apps clients can inspect logs without copying the complete result into the conversation:

browserless_logs({ levels: ["ERROR", "WARN"], limit: 50 })
browserless_show({ viewRef: "<returned-view-reference>" })

The explorer shows timestamp, severity, endpoint/event, outcome/status, category/reason, duration, units, and region. Expand a row for every returned field, including the complete message, target URL, request ID, and session ID. IDs have Copy buttons when the host grants clipboard write access. URLs remain plain text and never open automatically.

Filters cover the tool's existing time range, severity, endpoint, outcome, category, reason, request ID, target URL, event names, API key, page size, and ordering. Omitted time bounds use the account plan's server-defined window; retention errors appear in the widget. Refresh, Apply filters, and Load more call the authorized read-only logs tool through the bridge, without a new chat turn or another widget. Overlapping pages are deduplicated. Loaded entries are bounded to 500 rows and 2 MiB; each result page is limited to 100 rows and 1 MiB. If a result cannot fit in a view or storage is full, the tool returns its existing Markdown result instead of failing the log read.

When a view is prepared, rows, filter values, and opaque pagination cursors travel in widget-only metadata. Model-visible results contain a compact summary and view reference. The Markdown fallback includes entries and the next-page cursor as before. A mounted explorer that receives this fallback keeps its last successful snapshot and offers Retry. It also explains how to request the logs as text in chat and suggests narrower filters or fewer entries for large pages. Prompt text and filter values are excluded from logs-tool analytics. Existing Markdown output is unchanged for clients without MCP Apps. The compliant connector remains unchanged.

Snapshots expire after 15 minutes and share the existing bounded, process-local view store. Display rechecks account access. Refresh and pagination prepare a new snapshot; the mounted explorer adopts its expiry while older references keep their original deadline. Errors preserve the last successful result; expiry, cancellation, and loss of access stop further reads. Host locale and timezone control displayed timestamps. The optional model-diagnosis handoff is not included.

Inline account usage and active sessions

On the full surface, MCP Apps clients can display account snapshots:

browserless_usage({ timeframe: "day" })
browserless_show({ viewRef: "<returned-view-reference>" })

browserless_sessions({ action: "active" })
browserless_show({ viewRef: "<returned-view-reference>" })

Usage shows billed units against the plan allotment, highlights overage, and shows request counters when available. Billing-period units always cover the whole account; the hour/day/week selector applies only to request counters and preserves any API-key filter. Empty request counters never erase billed usage. Missing values remain unavailable.

Active sessions shows the browser ID, browser name/type, start time, and elapsed time at the snapshot. The API does not provide page URLs. Refresh preserves the original limit/skip filters and never stops or reconnects a browser.

Both controls call the original data tool through the widget bridge and update the mounted view without another chat turn or browserless_show call. Refresh errors preserve the last successful snapshot with a retry option. There is no automatic polling. Snapshots are independent, owned, bounded, and expire after 15 minutes; refreshing prepares a new reference and never renews an old one. The mounted widget adopts the new snapshot's expiry after a successful refresh. Showing a snapshot rechecks account access under the current credential. Clients without MCP Apps retain their original text output. These tools and widgets remain absent from the compliant connector.

Inline Lighthouse scorecard

In MCP Apps clients, browserless_performance displays a scorecard directly from the completed audit. Select a category and expand its initially collapsed failing-audits section to see every failure, ordered by reported savings. Expand a row for its description and reported savings. Five Lighthouse lab metrics accompany performance results. Missing categories are omitted; null scores and missing measurements remain unavailable. Scores use Lighthouse's 0–49, 50–89, and 90–100 bands and follow the host's light/dark theme.

The scorecard receives a bounded, typed summary rather than the raw report. It works on both surfaces without adding connector tools, making another API request, or loading external assets. The connector exposes only the scorecard's self-contained UI resource. Clients without MCP Apps keep their existing text output; the full surface also retains its JSON report download.

Inline human handoff

When an agent needs a person to complete a step, keep its existing browser open and prepare a handoff through browserless_live_url. The full HTTP surface and an MCP Apps client are required:

browserless_live_url({
  action: "handoff",
  sessionId: "<existing-agent-sessionId>",
  instructions: "Complete the verification, then choose Done.",
  timeout: 300000
})
browserless_show({ viewRef: "<returned-view-reference>" })

The widget embeds the existing interactive Live URL viewer, including its Done and Couldn't finish controls, and offers an external-viewer link when embedding is blocked. Its live capability stays in widget-only metadata. Reopening a view only reads the existing handoff; it never creates another link or browser.

Browser commands are blocked while a person has control. The widget reads browserless_handoff_state, an app-only tool, to confirm the backend outcome. After the person replies in chat, call browserless_live_url with action: "handoff_status" and the original viewRef. Resume with a fresh snapshot in the same session only when the reason is userDone. Failure, expiry, disconnection, and unavailable status do not count as success. After Done is confirmed, the widget asks the person to return to the conversation and type “Continue”. It does not send an automatic follow-up: tested ChatGPT widget-generated turns did not invoke the browser tool, while a typed reply did.

A temporary status-check failure leaves the live viewer open and asks the person to check status again before continuing. Confirmed closure, expiry, or loss of access removes the viewer. Explicit session close cancels its handoff; closed or retired widgets stop polling.

Handoffs default to five minutes, capped by the backend's browser deadline and 15-minute link limit. Creating, opening, or polling a handoff never extends the browser deadline. References are caller-bound and process-local, with at most 16 stored views and 16 unresolved handoff guards. Expired or disconnected handoffs still block automation and browser replacement until explicitly closed with the original session handle; completion releases the guard. These guards do not keep expired browsers alive. Reads recheck backend authorization, and an old view cannot release a newer handoff. The five-tool connector is unchanged. Clients without MCP Apps can continue using the agent's existing liveURL command for external viewers.

Modern backends return browserId with the live capability. For older Docker runtimes, MCP resolves the owned page through /sessions and replaces the old capability before publishing a fresh viewer. Ambiguous targets fail without launching another browser. The pause applies to commands through this MCP process; independent clients can still control the browser. Hosted /agent/run handoffs are a separate flow.

Local Docker and ngrok

The development runner serves MCP and proxies the existing Live URL viewer on one origin. It uses the existing Browserless Docker instance on port 5555; it does not start or modify the container. Build first, then run:

export BROWSERLESS_TOKEN="$(docker exec browserless-5555 printenv TOKEN)"
BROWSERLESS_API_URL=http://localhost:5555 \
BROWSERLESS_PUBLIC_URL=https://YOUR-DOMAIN.ngrok-free.dev \
PORT=8080 npm run start:local

In another terminal:

ngrok http http://127.0.0.1:8080 --url=https://YOUR-DOMAIN.ngrok-free.dev --inspect=false

Use No authentication in the MCP client and connect to https://YOUR-DOMAIN.ngrok-free.dev/mcp?token=<BROWSERLESS_TOKEN>. Keep the token private. BROWSERLESS_PUBLIC_URL changes only the viewer origin; backend API requests stay on localhost. The runner disables OAuth, analytics, and compliance mode for local testing. Its gateway listens on loopback and uses port 8088 for the internal MCP process (MCP_INTERNAL_PORT can change it).

Inline agent screenshots and recordings

On the full HTTP surface, MCP Apps clients can display screenshots and completed WebM recordings from browserless_agent. Set MCP_BASE_URL to the server's public HTTPS origin (HTTP loopback is supported for local testing). The agent keeps its existing text and image output and adds an exact viewRef in text when a media view is prepared. Pass that reference to browserless_show:

browserless_agent({ commands: [{ method: "screenshot", params: {} }] })
// Keeps the captured image and returns instructions containing its viewRef.
browserless_show({ viewRef: "<returned-view-reference>" })
// Displays the stored capture without repeating browser actions.

For video, set record: true on the call that opens the browser, then start recording, perform the requested browser actions, and call stopRecording. Display the reference returned by the call that completes the recording. For example, a user can ask: "Go to browserless.io, record the page while scrolling to the bottom, and show me the video inline."

The gallery contains captures from one tool call, with keyboard navigation, zoom, Save, and fullscreen controls. Recordings use native video controls. Preview bytes load directly from the MCP server through opaque, expiring bearer URLs in widget-only metadata. Anyone holding a preview URL can fetch that artifact until expiry; preview and Save requests are repeatable and do not consume the original single-use download.

Views expire after 15 minutes and share the replay store's 16-view, 128 MiB budget. Each caller scope retains at most four views across widget kinds. New views evict that caller's oldest views; they never evict another caller's views. A gallery shows the first 12 valid captures, each at most 50 MiB; its summary reports when more captures were returned. Invalid screenshots are skipped without discarding valid captures. Preview files are removed on expiry or eviction. Before the first media view is created, cleanup removes stale files left by exited processes, including files with the current process's reused PID. Storage remains process-local, so deployments must route requests to the owning process. Without MCP Apps support or a valid public origin, the agent retains its existing output without preparing a widget.

Native file staging (disabled by default)

The full HTTP surface advertises browserless_stage_file with the native openai/fileParams file descriptor. It is absent from stdio and the compliant surface. Native downloads are currently disabled: the production hostname allowlist is empty, so every staging request fails before DNS or network access. Tool inputs and environment variables cannot enable it.

The implementation accepts file.download_url and file.file_id, with optional file.mime_type and file.file_name. Once trusted hosts are verified and enabled in code, successful staging returns only { handle, filename, mimeType, size }. Pass the handle to browserless_agent's uploadFile; handles belong to the authenticated token, remain reusable for 15 minutes, and are not tied to an MCP transport. Stored MIME is inherited unless the upload supplies an override.

Controlled tests do not establish native ChatGPT attachment acceptance. Live attachment acceptance and handle resolution across deployed replicas remain unverified; the file store is process-local. Existing multipart /upload and inline-content uploads are unchanged.

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).

profile-import

src/skills/profile-import.md

Import the user's local Chrome/Brave/Edge sign-ins as a profile with the Browserless CLI (consent-gated, full surface 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" },
  },
}

Built-in proxy (browserless_agent)

Pass a top-level proxy object on browserless_agent to route the session through datacenter or residential IPs. Datacenter is cheaper per MB; residential is less likely to be blocked.

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

"datacenter" for lower cost or "residential" when targets block datacenter traffic.

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

Residential-only 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: Geo, sticky, and locale options require either a built-in proxy tier or externalProxyServer; proxyPreset requires proxy: "residential". The MCP rejects unsupported combinations instead of letting the API 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.

OS persona (browserless_agent)

Agent sessions can opt into a coherent OS persona with top-level creation options:

Field

Notes

emulationOs

"windows", "macos", "linux", "android", or "ios". Enables platform spoofing; android and ios select a mobile persona.

emulatedDevice

Mobile device slug (for example "pixel-8", "iphone-16", "ipad-pro-11"); used only with emulationOs: "android" or "ios". An omitted or unknown slug lets the server pick a device.

deviceType

"phone" (default) or "tablet". "tablet" selects an iPad and requires emulationOs: "ios"; Android accepts only "phone". A named emulatedDevice of the other kind is rejected by the server.

screen

Desktop screen in WIDTHxHEIGHT form.

deviceScaleFactor

Desktop device pixel ratio: 1 or 1.25.

deviceSlot

Non-negative stable desktop-device slot; the server validates the account-specific range.

For example, { "emulationOs": "ios", "deviceType": "tablet" } opens an iPad persona.

Set persona options on the first call before navigation and reuse the returned sessionId afterward. Persona is fixed for the life of that browser session; close it before selecting a different persona.

Configuration

The server is hosted at https://mcp.browserless.io/mcp. Authenticate via headers (preferred) or a ?token= query parameter. An API key the Browserless API reports as invalid is refused with HTTP 401 when the session opens; if the API cannot be reached in time, the session opens and tool calls report the key error instead.

Installing via an AI agent? See install.md for agent-readable setup instructions.

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.

API URL overrides are limited to browserless.io, its subdomains, the configured BROWSERLESS_API_URL origin (same scheme, hostname, and port), and hosts listed in MCP_ALLOWED_API_URL_HOSTS. Overrides for browserless.io and its subdomains must use https://, because the API token travels with each request; the configured origin is exempt. Paths are allowed, but credentials, query strings, and fragments (including bare ? or #) are not. Without an override, the operator-configured URL is used unchanged.

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)

MCP_ALLOWED_API_URL_HOSTS

No

—

Comma-separated hosts allowed for client-supplied API URL overrides, in addition to Browserless and the configured API origin

BROWSERLESS_API_SERVER

No

https://api.browserless.io

Account API host — backs browserless_account, _usage, _sessions and _logs. A different host from BROWSERLESS_API_URL, which is a browser runtime. Trusted: replay downloads fetch the signed link this API returns, so point it only at an endpoint you operate

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)

AMPLITUDE_API_KEY

No

—

Amplitude project API key. Sends MCP usage analytics — SDK lifecycle events plus our own tool/skill events

MCP_COMPLIANCE_MODE

No

unset (full surface)

Serve the reduced, directory-compliant surface. Fails closed: any set value except false/0/no/off enables it

Hosted OpenTelemetry

On httpStream, set OTEL_ENABLED=true and OTEL_EXPORTER_OTLP_ENDPOINT to a trusted collector's base URL. Metrics and stderr logs are exported over OTLP HTTP/protobuf; tracing is disabled. stdio never starts this SDK. OTEL_METRIC_EXPORT_INTERVAL controls the export interval in milliseconds (default 60000, minimum 1000).

NodeSDK manages the providers and standard Node runtime instrumentation emits nodejs.* and v8js.* metrics. Application session, tool, account and Redis metrics remain under browserless.mcp.*. All duration metrics use seconds (s), memory uses bytes (By), and request counters use {request}; application callers still supply milliseconds, converted once by the metric recorders.

browserless.mcp.auth.duration and .auth.in_flight cover POST authentication, not whole request execution. browserless.mcp.session.cleanup.age covers tracked MCP idle reaps and explicit/idle/cap agent cleanup, not every session close. Sweep-discovered MCP age starts at discovery; agent age resets on reconnect. browserless.mcp.accounts.active counts distinct token hashes per collection window. Top-account counts are an INFO log with body event browserless.mcp.account.window, active_accounts, and top_accounts (at most 20 {hash, count} entries), not persistent per-account metric series. An idle window emits no account log. Stderr text is INFO, console.warn is WARN, and arguments containing an Error are ERROR; stderr records carry log.iostream=stderr. OTEL_SDK_DISABLED=true also disables hosted telemetry.

For dashboards based on the initial telemetry PR: replace custom event-loop metrics with nodejs.eventloop.*, GC pauses with v8js.gc.duration, and active resources with v8js.resource.active. Drop _ms from tool/upstream/Redis duration names, use the auth and cleanup names above, and divide millisecond thresholds by 1000. Replace account.requests queries with the window logs. Duration histogram boundaries are also in seconds, covering sub-second Redis operations through two-hour sessions. Amplitude event fields and timeout configuration remain in milliseconds.

Skill retrieval diagnostics

Skill Retrieval Completed emits once per actual remote skill fetch through the existing analytics queue (when ANALYTICS_ENABLED, SQS_QUEUE_URL, and SQS_REGION are configured). It is not duplicated through the SDK's AMPLITUDE_API_KEY transport. Cache hits and concurrent callers sharing a fetch do not emit another completion. Failed retrievals remain retryable on the next call; this instrumentation adds no retries.

Fields are result=hit|miss|error, normalized domain, UUID request_id, source, attempt, integer duration_ms, stage=fetch|decode|validate, and available http_status. skill_count appears only on valid responses: positive for hits, zero for misses. Errors carry error_category=timeout|network_error|http_error|invalid_json|invalid_shape. Sources are cli_agent, script_builder, autologin, agent_run, mcp_client, or unknown. Each fetch currently has attempt=1; no run identifier is available at these call sites, so run_id is omitted. Domains outside the bounded hostname format become invalid without dropping the completion from the denominator.

Set OTEL_EXPORTER_OTLP_LOGS_ENDPOINT to a trusted collector's full /v1/logs URL to export matching skill.retrieval.failed WARN records as OTLP/HTTP JSON. The default is disabled. Exports have a one-second deadline, at most 16 in-flight requests, and no retry. Caught queue/skill analytics errors produce skill.telemetry.delivery_failed with originating_event and the fixed diagnostic category delivery_error, at most once per minute per process. Exporter failures are swallowed without recursively reporting themselves. No new log contains tokens, prompts, full URLs, response bodies, or recipe text. The queue retains its existing authentication field, separately from log fields.

Example failure attributes:

{
  "event.name": "skill.retrieval.failed",
  "result": "error",
  "domain": "shop.example",
  "request_id": "416e0409-25e2-4399-a3fa-6939f43a75e0",
  "source": "mcp_client",
  "attempt": 1,
  "stage": "fetch",
  "error_category": "http_error",
  "http_status": 429,
  "duration_ms": 17
}

Retrieval error rate is error completions / all completions. Hit rate is hit completions / valid completions. Do not add the separate server Skill Lookup events to either denominator. Tests use local/mock sinks; a configured exporter or console message is not proof of remote receipt.

Session and analytics-delivery diagnostics

On the full httpStream surface, each ready session emits an INFO browserless.mcp.session.open OTLP record with transport, auth_method, key_fp (a 16-hex token fingerprint), source, client_family, user_agent_family, and usage_mode. Known account IDs are included. Client names/versions use 128-code-point escaped previews in both logs and queue events. Source and UA families use known labels or unknown; no raw token or UA in log/event properties. The compliant surface and stdio do not emit session-open records.

MCP Session Started uses only the existing authenticated analytics queue, never the SDK transport: full-surface SSE sessions only, when analytics is enabled. The queue consumer resolves identity using its authentication field.

browserless.mcp.amplitude.delivery_failed WARN records aggregate event_type, integer status, sanitized reason, count, and window_s=60. Each window holds at most 12 distinct keys plus one overflow record. Reasons drop text after the first colon, redact key-like runs and email-like words, and escape a bounded preview. One stderr summary per window replaces per-failure SDK lines; real status counts survive overflow. Shutdown awaits final/in-flight exports with the exporter's one-second deadline.

Failure diagnostics

MCP Tool Request retains analytics_version=2, the existing coarse error_category, status_code, timing and tool-specific properties. These additive diagnostic fields are failure-only; a successful retry has none of them.

Property

Meaning

error_reason

selector_miss, invalid_params, unknown_method, script_error, unauthorized, forbidden, not_found, server_error, session_lost, navigation_failed, timeout, rate_limited, no_results, response_too_large, or unknown. Agent errors retain their existing detailed classification; local URL/batch validation is invalid_params.

error_source

validation, script, target_website, api, transport, or unknown. This identifies the observed failure boundary, not blame. A 403 alone does not identify its source.

failed_command_index

Zero-based index in the invocation's command batch, not the session-wide command counter. Omitted when setup/validation fails before a command starts.

failed_method

The failed command's recognized typed method name. Unrecognized free-form method names are omitted to avoid emitting arbitrary input; the index still identifies the command.

error_code

Allowlisted structured codes: the uppercase reason names above, SELECTOR_NOT_FOUND, BROWSER_CRASHED, ECONNRESET, ECONNREFUSED, ENOTFOUND, EAI_AGAIN, ETIMEDOUT. Opaque/unrecognized codes are omitted, not copied into messages.

error_status_code

An integer HTTP status (100–599) carried by structured error metadata. Never extracted from error prose.

error_status_origin

api for an observed API response/upgrade, target_website for a failed navigation result, otherwise unknown. Omitted when no structured status is available.

error_message

A synthesized summary capped at 500 characters. Raw error messages, response bodies, HTML, scripts, selectors, credentials, cookies, authorization headers and URLs are never copied into this field.

For browserless_function, browserless_export and browserless_smartscraper, a failed result's recorded status_code sets the reason: 400 from the function tool → script_error (source script), other 400 and 422 → invalid_params, 401 → unauthorized, 403 → forbidden, 404 → not_found, 408 → timeout, 429 → rate_limited, 5xx → server_error, anything else → unknown. Function and export statuses are the Browserless API's (error_status_origin=api); smart scraper statuses are the target website's (error_status_origin=target_website, error_source=target_website). A function text result over the size limit is response_too_large (source script). Without a status, the generic codes INTERNAL_ERROR and TAB_NOT_FOUND map to server_error and not_found.

status_code keeps its original tool-specific meaning; the new status fields do not replace it or turn successful target-page HTTP responses into failures. HTTP failures retain API response status even when thrown. Codes are retained when already available in structured errors or the JSON body read by the existing 4xx error handler; diagnostics do not read additional bodies on 5xx failures.

An unsuccessful search classifies the backend's errorCode (source api, kept in error_code): upstream_timeout → timeout, upstream_unavailable → server_error, no_results → no_results. One without structured evidence reports error_reason=unknown and error_message="Unclassified search failure.". Its legacy user_error category remains for chart compatibility, not as evidence of caller fault.

Example breakdowns: filter success=false and group by tool → error_reason; for agent calls, group by failed_method → error_reason; for HTTP failures, group by error_status_origin → error_status_code. Missing fields in older events mean unavailable instrumentation, not an unknown failure. There is no historical backfill. Verify representative received events after deployment before treating these properties as available in production.

Live URL instructions

browserless_live_url creates viewer links over REST for an existing browser. On the full HTTP surface, action: "create" opens an inline live viewer for clients that advertise MCP Apps support. The original JSON result, including the viewer URL, remains in content for clients that advertise Apps support but do not render widgets. The widget reads its viewer URL from _meta; IDs and lifetime metadata are available in structuredContent. Direct viewers do not use the shared snapshot store. If a successful create cannot be embedded, its JSON result is still returned instead of failing the mutation or creating another link.

Non-create actions render no widget content. The viewer's local disconnect timer uses the server-reported remaining duration, not the client's wall clock. The backend enforces the actual link lifetime, including for delayed or restored results; the local timer is not an authorization check.

status and close return lifecycle results without embedding a viewer. Direct creation does not keep the browser alive or pause automation. To pause an agent for human input, use handoff → browserless_show and then handoff_status.

Set action: "create", browserId, and interactable: true for an interactive viewer:

{
  "action": "create",
  "browserId": "running-browser-id",
  "interactable": true,
  "instructions": {
    "layout": "panel",
    "format": "markdown",
    "title": "Complete sign in",
    "summary": "Enter your **verification code**.",
    "steps": ["Open your inbox", "Enter the code"],
    "currentStep": 2
  },
  "doneLabel": "Continue",
  "failLabel": "Need help",
  "requesterName": "Support"
}

Interactive browserless_agent live URLs and browserless_live_url interactive creates and inline handoffs default to "Complete the step shown on screen, then use the completion button." when instructions is omitted. Pass specific instructions when possible. Agent links with interactable: false and view-only REST creates have no default instructions. An explicit empty or whitespace-only string disables the card and Done button for agent links and REST creates. Inline handoff requires nonblank plain-text instructions when supplied; blank text is rejected.

Plain string instructions still work. With a string, use top-level instructionsTitle, steps, currentStep, and instructionsFormat. With an object, put these values inside instructions as title, steps, currentStep, and format. Button labels and requester name stay top-level. Titles allow 80 characters; up to 10 non-empty steps allow 300 characters each; button labels allow 40 characters; requester names allow 60 characters. currentStep is one-based and must refer to a supplied step. Summary text is trimmed and capped at 2048 characters by the server. Steps-only cards are supported. Markdown links must use HTTP or HTTPS. The server validates cross-field constraints; deployments must support rich REST instructions.

MCP Resources

Resource URI

Description

browserless://api-docs

Smart scraper API documentation

browserless://status

Live service health status

ui://browserless/view/v12.html

Bundled replay, screenshot, video, handoff, account usage, active sessions, and request-log explorer widget (full surface only)

The previous ui://browserless/view/v1.html through ui://browserless/view/v11.html resources remain readable as aliases of the current widget. Newly discovered tools advertise v12 so hosts discover the request-log explorer.

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.x and 26.x. Development and publishing use Node 26 from .nvmrc; with nvm, run nvm install and nvm use. PRs must keep the suite green before they can merge.

The published package retains its Node.js >=24 engine requirement; Node 22 is not supported. Use an LTS release (24 or 26). Docker uses a digest-pinned Node 26 Trixie image, with weekly Dependabot digest updates and Node-major upgrades excluded. Official Linux Node 26 binaries require libatomic; the image includes libatomic1. Container publishing targets Linux amd64 and arm64.

API Token

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

License

SSPL-1.0

Available Tools

21 tools
browserless_accountA
Read-onlyIdempotent
Inspect

Read the Browserless account behind the current API token: plan, unit balance, billing period, and the names of the account API keys. Use it to answer "what plan am I on", "how many units are left", or "which keys exist". Read-only, and never returns API token values.

Inputs: action (required), _prompt.

browserless_agentA
Destructive
Inspect

READ CAREFULLY: Execute browser commands in an agent session.

Core Loop (ReAct: Reason → Act → Observe)

  1. Plan + check for a site recipe — restate the goal, decide the target host, then browserless_skill { site: "<host>" } (see above). Load and follow any matching recipe before writing your own plan. Never jump straight to goto.

  2. goto — waits "domcontentloaded"

  3. snapshot — returns interactive + informational elements (button, link, textbox, combobox, checkbox, heading, img+alt) with ref= selectors

  4. Plan all actions from snapshot

  5. Batch execute

  6. Re-snapshot only if page changed

  7. Repeat → close when done

Ending the session (REQUIRED)

One-shot vs. multi-step (session lifetime). Sessions are one-shot by default: when your commands batch and download drain finish, the browser closes and frees its slot. Decide on your FIRST call:

  • One batch finishes the whole task (e.g. goto + text/html/evaluate to read something): leave it one-shot; it closes automatically.

  • You must look, then act on what you see — any first batch that ends on a snapshot so you can plan later clicks/typing: set keepSessionAlive: true on that first call. The observe-then-act loop spans calls, so this covers most interactive work.

  • Unsure? Set keepSessionAlive: true. A kept session still auto-reaps when idle; a wrongly-closed one loses your page, login and progress. After a keepSessionAlive: true call, pass the returned sessionId back on every later call — it stays alive, no need to repeat the flag. Set keepSessionAlive: false to force-close even when continuing. Profile creation and attached sessions manage their lifetimes separately.

When a step requires human input or you cannot safely proceed without help, stop browser actions and preserve that session. Use an available human-handoff capability to show the browser with specific instructions, then ask the person to finish the step and reply. Never ask them to paste passwords or verification codes into chat. Wait for confirmed completion before taking a fresh snapshot and continuing in the same browser; do not open a replacement or assume that opening a viewer completed the step.

An open session holds one of the account's concurrent browsers until it idles out — leaving it open is not free, and stacking them starves the next task. Report the outcome (only if you loaded a site recipe). Near the end of the run, send { method: "reportSkillOutcome", params: { domain: "<host>", task: "<slug>", success: <bool> } } inside commands — where domain/task are the loaded recipe's <host>/<slug> and success is false if a step in this recipe failed as written, even if you finished another way. Cosmetic differences that didn't break a step are still success: true. This refines shared recipes and retires ones that stop working. Send it once, and only when you loaded a recipe — never for a self-planned run. Send it before reportOutcome and any close (close ends the run and anything after it is dropped). When the loaded recipe's footer shows run_id, skill_use_id and loaded_version, include all three exactly as shown; never invent or alter them, and never send attribution_status. On failure, add one bounded failure_reason: authentication_required (login needed), site_changed (a URL or element no longer matches), blocked (access denied or challenge), timeout (operation timed out), missing_data (required output absent), incorrect_result (output present but wrong), or unknown (cause unclear). For example: { method: "reportSkillOutcome", params: { domain: "example.com", task: "search", success: false, failure_reason: "missing_data" } }. On success, omit failure_reason; success with a failure reason is invalid. Boolean-only legacy reports remain valid; failures default to unknown. These are agent-reported results, not independent validation. Never supply outcome_source: the server assigns provenance. Do not put URLs, secrets, prompts, copied content, or free-form explanations in outcome fields.

  • Report the outcome after you've seen the results. Once the task is done or you are giving up, and you have seen the final results, send { "method": "reportOutcome", "params": { "success": <bool> } } once per task (it costs nothing and is not a page action). If success is false, add "reason": blocked_by_site, captcha, login_required, timeout, or other. Kept-alive session: include it in the batch before close, or send it alone before close. One-shot call: send it as its own call with the sessionId the one-shot reply gives you, which opens no browser.

  • Kept-alive task complete? Close it. Send { "method": "close" } as its own call, as the last thing you do.

  • Ask instead of guessing only when follow-up in the SAME browser is genuinely likely (the user said "then...", you're mid-flow on a logged-in site, or the result invites a next step). Say the browser is still open, ask whether to close it, and close it as soon as they're done.

  • Never end your reply with a live session and no mention of it. Either it's closed, or you told the user it's open and why.

Site recipes (site-specific, NOT auto-injected) — CHECK FIRST

Many specific sites (marketplaces, gov portals, travel, real-estate, etc.) have a tuned recipe for a given task — proven selectors, API shortcuts, proxy needs, and known gotchas that a from-scratch plan will miss. These are not auto-injected; you must ask for them, and a recipe overrides any plan you'd build yourself (including "just use a prefiltered URL + evaluate"). This is step 0 of every task — do it before your first goto. The moment you know the target host (the user named the site, or you resolved which site to use), call browserless_skill { site: "<host>" } — e.g. { site: "airbnb.com" }. If it lists a recipe matching your task, load it with browserless_skill { id: "<host>/<slug>" } and follow it. Only when there's no match do you plan the steps yourself. Skipping this check on a supported site is a mistake — it's one cheap call.

Proxy (optional)

Proxy config is a top-level proxy object on the tool call — it is applied when the session is opened. NEVER call proxy as a method inside commands — a { method: "proxy", ... } JSON-RPC mutation does NOT change the upstream proxy on an already-open session and will silently no-op.

If there is credible evidence the task needs a proxy, you MUST pass proxy options on the very FIRST call (before any goto/snapshot), because the config is read once at session creation. Credible signals include: the user asks for a specific country/region/locale; the target site is known to geo-restrict or block datacenter IPs (streaming, ticketing, retail, banking, real-estate, news paywalls); a prior attempt returned 403/451/captcha/"unusual traffic"/"access denied"; the user explicitly mentions residential / sticky IP / proxy.

If you already opened a session without a proxy and now realize one is needed, you must close and start a new session with the proxy options set — there is no in-session switch.

  • Use proxy: { proxy: "datacenter" } when a lower-cost IP is sufficient. Use proxy: { proxy: "residential" } when the target is known to block datacenter IPs or the cheaper tier still hits a challenge.

  • Inside the object: proxyCountry: "us" — geo (ISO-2); proxyState / proxyCity (paid plans, 401 otherwise); proxySticky: true — stable IP; proxyLocaleMatch: true — match locale; proxyPreset — residential-only named config; externalProxyServer: "http://u:p@host:port" — bring your own (http(s) only)

  • Geo/sticky/locale options require a built-in proxy tier or externalProxyServer; proxyPreset requires proxy: "residential"

OS persona (optional)

The top-level emulationOs, emulatedDevice, screen, deviceScaleFactor, and deviceSlot options are read once when the session opens. Put them on the very first call, before any goto, then keep using the returned sessionId; close and open a new session to change them.

Reach for emulationOs only when there is evidence of platform fingerprinting: a Cloudflare or similar interstitial that never resolves, a hard block on an otherwise healthy page, or a site known to inspect the operating system. Start with emulationOs: "windows" unless the task or site requires another OS. Use emulatedDevice only with Android; desktop screen, deviceScaleFactor, and deviceSlot refine a desktop persona.

Auth

While secret protection is armed, getTabs exposes only tab IDs and active flags, and switchTab only success and the target ID; neither exposes titles or URLs. Use these to run waitForSelector removal checks in each tab, including hidden filled fields. Recheck new tabs before clearing and return to the destination. Navigation never clears the local guard. A completed redirect permits removal verification without a signed-in marker, not clearing without verification. Unknown or inaccessible secret-bearing surfaces must fail closed; these commands do not certify that arbitrary copied secrets are absent.

For an existing-profile session, set keepSessionAlive: true on the initial call so the browser stays open for the required next-batch saved-login report.

Never log in or register by default. Never invent or assume credentials exist (no "test credentials", no "your account"). If the snapshot contains a sign-in link OR you're about to mention "sign in" / "log in" / "auth required" — even as a suggested option to the user — call browserless_skill { id: "autonomous-login" } first — or { id: "autonomous-registration" } when the task is to create an account / sign up / register —, then follow its gates. The skill decides whether login is appropriate and whether credentials are in scope; do not skip it just because no password field is on the page yet.

After a loadSecret login, snapshot, screenshot, PDF, liveURL, and page-content reads (evaluate/html/text) are subject to capture protection. Navigation alone does not unlock backend captures. Only after the fill completes and secret-bearing content is gone from all tabs, including hidden fields, send { method: "clearSecrets" } before requesting a fresh snapshot or capture. If those conditions cannot be confirmed, do not clear to inspect the page. An accepted clear also invalidates snapshots already in flight; request a new snapshot after unlocking.

Saved-login check (only when the session was opened with profile). After the first batch that loads a page on each site — however you read it (snapshot, text, evaluate, or screenshot) — send { "method": "reportProfileAuthentication", "params": { "checkpointId": "<host>:first-page", "outcome": "<authenticated | login_required | challenge | unknown>", "newLoginActivity": false } } as the FIRST command of your NEXT commands batch, before any login actions; the rest of that batch can continue the task, but not with close. If login activity already occurred on this site, use newLoginActivity: true instead. It defaults to the last active-tab snapshot, so if you have not taken one yet, end that first page-load batch with snapshot; if you used snapshot { targetId } to peek at another tab, repeat that targetId in the report. Report authenticated only when the page shows a signed-in element (account menu, sign-out link, avatar); a 200 page, cookies, or a non-login URL alone is unknown. Report login_required for a sign-in form or wall, challenge for a captcha or verification wall. If you later log in on that site (typed credentials, loadSecret, or the autonomous-login skill), send one more report for that site with "newLoginActivity": true and a new checkpoint label such as "<host>:after-login". It is not a page action, costs nothing, and is allowed right after loadSecret. Never send it on sessions without profile.

Pass sessionId on every follow-up call, including reports and close; the session handle retains the profile, so repeating profile is optional.

Terminal-Goal Check

Before declaring done, restate the user's terminal deliverable in one line and verify your evidence directly supports it — not a sibling question. Empty-state substitution. An empty/zero/null result from a resource that normally requires auth, scope, or filter context is evidence the precondition wasn't met — not evidence the question is answered. Empty cart while logged out, zero results while geo-restricted, empty inbox while unauthenticated: precondition failure → fix the precondition (often: load autonomous-login), don't return the empty result as the answer. Multi-step preconditions. When the task names multiple steps ("go to X, then Y, report Z"), evaluate preconditions for the full chain before treating any step as optional. A blocker on step N blocks the whole task even if step 1 returned data.

Skills (auto-injected)

SKILL blocks auto-inject between --- SKILL: <id> --- markers when page/error needs special handling. Read carefully. Load manually via browserless_skill if suspected but not injected:

  • autonomous-login — gates, credential rules, MFA/captcha, how to report the outcome (see ## Auth above for when to load)

  • autonomous-registration — create-account flows: gates, identity and credential-sink rules, save-first-then-loadSecret password handling, emailed-code branch, how to report the outcome

  • shadow-dom — deep selectors, iframe targeting

  • cookie-consent — vendor-specific dismiss recipes

  • modals — closing dialogs and alertdialogs

  • captchas — the solve command (Cloud only)

  • snapshot-misses — truncated/empty snapshots, image-rendered content

  • dynamic-content — choosing the right wait* method

  • screenshots — when to screenshot vs. snapshot, scope and format choices

  • vision-fallback — click by coordinate when the snapshot can't surface an element

  • tabs — multi-tab workflows, peek-without-switching

Snapshot Rules

  • Until you snapshot a page, you CANNOT click/type/interact — snapshot first, no exceptions

  • NEVER guess, assume, or infer selectors — CSS selectors from your training data are wrong. ONLY use ref= / deep-ref= from latest snapshot

  • Snapshot STALE after: click, goto, select, navigation

  • Snapshot VALID after: type, hover, scroll, evaluate

  • Expect new content? → re-snapshot

  • Element roles in snapshot (link, button, textbox, combobox, checkbox, heading) tell you what each does

  • Snapshot lines may include desc="...", action=METHOD URL, autocomplete=..., and intent markers (⚠ destructive, ⚠ sign-out, sign-in, reset)

  • Before activating or navigating to a control marked ⚠ destructive or ⚠ sign-out, confirm that the action is actually intended; an unlabeled destructive control is a common trap

  • Snapshots after the first return a diff vs. your previous snapshot: only + new / ~ changed / - removed elements, plus a count of unchanged ones omitted. Unchanged elements stay valid — keep using their refs from the earlier snapshot. If that earlier snapshot is no longer in your context (summarized/trimmed away), request snapshot { full: true } to get the complete element list again.

Selectors

  • Use ref= (CSS) or deep-ref= (starts < ) exactly as shown in snapshot

  • Example: [3] button "Sign In" ref=button#submit → "button#submit"

  • deep-ref for shadow DOM / iframes — see shadow-dom skill

Iframes

Snapshots include a Frames list (cross-origin iframes) when present. Elements inside a frame are tagged [frame#N] and carry a deep-ref=< *url* css selector that already pierces the frame — pass it as-is to click/type/hover/checkbox. No frame switching needed. captcha/payment widgets (reCAPTCHA, hCaptcha, Stripe, Turnstile) show up here. shadow-dom skill auto-loads when frames present.

Tabs

Snapshots include tabs + activeTargetId — no getTabs needed. Multi-tab / snapshot { targetId } in tabs skill (auto-loads when >1 tab).

Prefer goto over click for links with href — immune to layout shifts, overlays, misclicks. Example: [5] a "About" ref=a[href='/about'] → goto { url: "https://ex.com/about" } Only click when href is javascript: / # / missing.

Content Extraction

  1. Check in-memory snapshot (text/values already there)

  2. text { selector } — from specific element

  3. evaluate { content } — JS (IIFE): (() => { return ... })()

  4. html { selector } — raw HTML

Files (upload / download)

To download a file, DRIVE THE BROWSER first. Login/cookie-gated or generated downloads often have no directly fetchable URL. Click/goto in the agent and collect the captured artifact, then follow its delivery instructions. NEVER read a file's bytes or base64 into this conversation, and NEVER split/reassemble/inline base64 by hand. That is the wrong tool and will stall.

  • Upload a local file (stdio): uploadFile { selector, files: [{ path }] } — the server reads + encodes it only inside the download directory or a directory explicitly allowed by the local operator through BROWSERLESS_UPLOAD_DIRS. Symlink targets must also be inside an allowed directory. Ask the operator about rejected paths; do not bypass the restriction by reading or moving the file yourself.

  • Upload a local file (HTTP): the server can't read your disk. Use a supported client staging path and its returned handle. Legacy clients permitted to use local authentication can follow the authenticated /upload instructions supplied by the server. Native clients must report unsupported staging rather than read local credentials.

  • Re-upload something from getDownloads: pass its handle (works in both modes).

  • Download: captured files auto-surface as metadata. stdio gives a local path. In HTTP mode, follow the artifact's delivery mode: mcp-resource requires a client/tool/runtime verified to save resource blobs to disk without payloads in model requests; if unavailable or unverified, report unsupported saving without reading the resource. Legacy HTTP delivery retains its authenticated save instructions, usable only where local credential access is permitted. Native delivery never falls back to shell authentication, inline bytes, or source URLs. Both routes authenticate the owner and share single-use consumption; files expire after 15 minutes or session cleanup. Check the saved file exists and its size before claiming success. A transfer failure after consumption does not authorize repeating browser actions to regenerate it.

  • base64 content is a LAST RESORT — tiny inline data only.

  • Full recipe: file-transfers skill.

Batching — Maximize Per Call

Plan ALL actions from snapshot before next snapshot.

Process:

  1. Classify actions: safe (type, hover, scroll, evaluate, select, checkbox) vs. page-changing (click, goto)

  2. Batch: safe FIRST → page-changing LAST

  3. For forms: if submit button is in snapshot, batch type + click in one call

  4. Don't batch across navigations

Example form:

{ "commands": [
  { "method": "type", "params": { "selector": "input#email", "text": "j@d.com" } },
  { "method": "click", "params": { "selector": "button#submit" } }
] }

Async

After async triggers (search, submit), use wait* before snapshot — waitForResponse best when API URL known. dynamic-content skill auto-loads on timeout. Never evaluate with setTimeout.

Error Recovery

Errors tagged Category: <NAME>:

  • SELECTOR_MISS — re-snapshot; retry < selector if not already deep-ref

  • SESSION_LOST — a fresh session was opened automatically; re-goto + snapshot (prior state gone)

  • UNAUTHORIZED / FORBIDDEN — pick different path

  • NOT_FOUND — different URL

  • SERVER_ERROR — backoff, retry once

  • NAVIGATION_FAILED — verify URL

  • TIMEOUT — longer wait or different signal

  • INVALID_PARAMS — fix params (schema authoritative)

  • UNKNOWN_METHOD — no such method; pick one from the schema

  • SCRIPT_ERROR — your evaluate script threw; page still alive, fix the script

  • UNKNOWN — re-snapshot + re-plan

! NOTICE: URL changed cross-origin = prior plan/refs invalid, re-plan. Never retry same failed action without re-snapshot.

Methods (non-obvious)

  • goto { url, waitUntil? } — default "domcontentloaded"; prefer over click for links

  • snapshot { maxElements?, targetId? } — cap 500; targetId peeks non-active tab

  • evaluate { content } — IIFE only

  • waitForSelector { selector, timeout? } — set 5000-10000ms

  • waitForResponse { url?, statuses?, timeout? } — url is glob "*api/results*"

  • createTab { url?, activate?, waitUntil? } — default activate: true; false = background

  • loadSecret { ref, selector? } — fills a vault secret server-side (op://<vault>/<item>/<field>, or mail://<vault>/<inbox item>/otp for an emailed code); you never see the value; arms capture protection, including snapshots. Navigation alone does not unlock captures

  • saveSecret { title, username, password, website?, vault? } → { ok, ref } or { ok: false, error, vaults? } — needs integrationId on the FIRST call; omit vault unless the result lists several

  • clearSecrets {} — lowers capture protection; use only after the fill completes and secret-bearing content is gone from all tabs, including hidden fields, never just after clicking submit. Then request a fresh snapshot. waitForNavigation/waitForResponse/waitForSelector are allowed while armed but do not unlock snapshots

  • close — own call, NOT batched; only when task complete (premature close discards page state)

  • liveURL { timeout?, instructions? } — defaults to 300000ms (five minutes); server caps the requested lifetime at your plan's maximum session time and remaining browser time. For a human handoff, pass specific instructions explaining what to do and when to click Done. Interactive links supply generic instructions when omitted; an empty string disables the card and Done button. Set keepSessionAlive: true on the handoff call, reuse the returned sessionId, and close the browser when the overall task finishes. Creating a link does not extend the browser deadline; keeping the browser open remains billed.

  • See schema for: screenshot, solve, back, forward, reload, click, type, select, checkbox, hover, scroll, text, html, waitForNavigation, waitForTimeout, waitForRequest, liveURL, getTabs, switchTab, closeTab

Runtime: LOCAL (stdio)

Before any file transfer, know your mode: this server runs over stdio, on the same machine as your files. To UPLOAD a local file, pass its path to uploadFile (files: [{ path }]). The path and any symlink target must be inside the download directory or a directory the local operator explicitly allowed through BROWSERLESS_UPLOAD_DIRS. Ask the operator about rejected paths; do not read or move the file to bypass the restriction. Do NOT base64 the file or read its bytes into the conversation. DOWNLOADS are saved to local disk; the agent response gives you the path.

Repetition self-check

When a tool response contains REPETITION WARNING, re-read your plan and compare your completed steps with the intended progress. Do not repeat the same batch blindly: choose a materially different approach within the task's constraints, or stop and report what is blocked and what you tried. Repetition is a signal to check progress, not proof of failure; continue a repeated action only when you can identify concrete progress or a task-required reason.

Inputs: os, proxy, method, params, +17 more.

browserless_crawlA
Read-only
Inspect

Crawl a website and scrape every discovered page using Browserless. Starts from a seed URL and follows links up to a configurable depth. Supports sitemap discovery, path filtering, subdomain handling, and custom scrape options. Returns scraped content (markdown/HTML) for each page along with metadata. Useful for comprehensive site analysis, content extraction, and data gathering.

Inputs: url (required), delay, limit, _prompt, +13 more.

browserless_exportA
Read-only
Inspect

Export a webpage from a URL via the Browserless /export API. Fetches the URL and returns its content in the native format (HTML, PDF, image, etc.). Automatically detects the content type. Set includeResources=true to bundle all page assets (CSS, JS, images) into a ZIP archive for offline use.

Inputs: url (required), toDisk, _prompt, profile, +5 more.

browserless_functionA
Destructive
Inspect

Execute custom Puppeteer JavaScript code on the Browserless cloud. Your function receives a Puppeteer page object and optional context data.

Set toDisk=true to save any result, including JSON/text, outside the conversation. Native MCP sessions save binary results by default; toDisk=false explicitly requests inline analysis. Saving follows the returned delivery instructions and requires a verified client path.

For inline analysis: What the function returns decides the response:

  • Bytes (a Uint8Array), e.g. return await page.screenshot({ type: "jpeg" }) or return await page.pdf(): the file type is detected from the bytes. PNG/JPEG/WebP → vision content block (~1.5K tokens); MP3/WAV → audio content block; PDF and other files → resource content block (attachment)

  • A string → text

  • Any other object or array → JSON text. A { data, type } wrapper is NOT unwrapped, so wrapped bytes come back as a huge JSON text that fails the limit below

Return the Uint8Array as-is: Buffer is not available inside the function, and a base64 string comes back as text, not an image.

Text responses are capped at 200,000 characters (~50K tokens). Larger text payloads will be rejected — filter or summarize inside your function, or return the raw bytes if you actually meant to return a file.

Useful for complex scraping, form filling, or any browser automation that requires custom code.

Inputs: code (required), toDisk, _prompt, context, +2 more.

browserless_live_urlA
Destructive
Inspect

Create, inspect, or close a live viewer link for an existing browser through REST, without an agent connection. In MCP Apps clients, create displays the viewer inline; other clients receive the viewer URL as JSON. Direct create does not pause automation. Create options default on the server: view-only, jpeg, quality 70, not resizable, browser interface shown. Link lifetime defaults to 15 minutes, capped by your plan's maximum session time and remaining browser time; creating a link does not keep the browser alive. For a human handoff, pass instructions explaining what to do and when to click Done. Interactive creates and handoffs supply a generic instruction when omitted. For create, an empty string disables the card and Done button; view-only creates have no default instructions. Instructions accept a string or an object with layout, format, title, summary, steps, and currentStep. For string instructions use instructionsTitle, steps, currentStep, and instructionsFormat beside instructions. doneLabel, failLabel, and requesterName are always top-level options. Status returns status, reason, interactable, viewerCount, and expiresAt (epoch ms). Ended links remain inspectable until their browser closes; closing an ended link returns not found.

Inputs: action (required), type, steps, _prompt, +16 more.

browserless_logsA
Read-onlyIdempotent
Inspect

Read Browserless's own record of the account's recent requests: what was attempted, whether it failed, why it stopped, how long it took and what it cost. This is the tool for diagnosing a run that failed on the Browserless side rather than in your own code. The window available depends on the account plan; the server reports the limit if a range is refused. Read-only. When an inline view can be prepared, MCP Apps clients receive a viewRef; use browserless_show to display the request-log explorer. Its rows and pagination cursors stay in widget-only metadata. Otherwise returns the standard Markdown result.

Inputs: url, limit, order, cursor, +10 more.

browserless_mapA
Read-only
Inspect

Discover and map all URLs on a website using Browserless. Scans a site via sitemaps and link extraction to find all pages. Returns a list of URLs with optional titles and descriptions. Use the search parameter to order results by relevance to a query. Useful for site audits, content discovery, and building site maps.

Inputs: url (required), limit, search, _prompt, +4 more.

browserless_performanceA
Read-only
Inspect

Run a Lighthouse performance audit on any URL via the Browserless /performance API. Returns scores and metrics for accessibility, best practices, performance, PWA, and SEO. Optionally filter by category, emulate a mobile or desktop device, supply a custom Lighthouse config, or supply performance budgets. Returns category scores and available Lighthouse lab metrics inline: FCP, LCP, TBT, CLS, Speed Index, initial server response time, and total transfer size. Use these metrics to answer page-speed questions without writing timing scripts. INP is not measured by this navigation audit; TBT is a responsiveness proxy. Saves the full JSON report outside the conversation. Follow its delivery instructions to save locally and inspect only the audits you need. Note: audits can take 30s–120s depending on the site. In clients with inline widgets, returns a pending audit reference immediately; the widget runs the audit and displays results. Do not repeat or poll the audit. Use browserless_performance_result for follow-up analysis of a completed audit.

Inputs: url (required), config, device, _prompt, +4 more.

browserless_performance_resultA
Read-onlyIdempotent
Inspect

Retrieve an existing inline Lighthouse audit for follow-up analysis using its exact auditRef. Never starts or repeats an audit. If still pending, let the widget finish; do not poll.

Inputs: auditRef (required).

browserless_performance_runA
Read-only
Inspect

Widget-only execution of a prepared Lighthouse audit. Repeated requests reuse the same audit.

Inputs: auditRef (required).

browserless_profilesA
Read-only
Inspect

List the authentication profiles saved for the current token. A profile is a saved logged-in browser state (cookies + storage) that can be replayed by passing its name as profile to other tools. Call this before a task that needs the browser to start signed in, to discover which profiles already exist and pick one by name. Returns each profile name plus cookie/origin counts and last-used time.

Inputs: limit, offset, _prompt.

browserless_sessionsA
Read-onlyIdempotent
Inspect

Inspect the sessions on the Browserless account behind the current API token: browsers running right now, persistent sessions saved on dedicated workers, recorded session replays, and 1Password credential integrations. Use it to answer "what is running", "did my session survive", or "what got recorded". Read-only — it never stops a session. Action replay downloads one recording and returns a fully self-contained playable rrweb page, needing no network to render: display it inline if you can render HTML, otherwise build an artifact from the returned instructions so the user can watch it. Always show the replay — never just summarise it in words. For MCP Apps clients, actions active and replay return a viewRef without rendering. Call browserless_show with that exact reference to display the result; do not read or repeat recording data.

Inputs: action (required), page, skip, limit, +3 more.

browserless_showA
Read-onlyIdempotent
Inspect

Display a prepared Browserless replay, screenshot gallery, video, human handoff, account usage, active sessions, or request-log explorer inline. Pass the exact viewRef returned by its producer tool. Never repeats browser actions, downloads, or creates another handoff.

Inputs: viewRef (required). Returns: data, kind, summary, viewRef, +1 more

browserless_skillA
Read-only
Inspect

Load a Browserless agent skill on demand, or discover site-specific recipes.

Two uses:

  • { site: "" } — list any site-specific recipes tuned for that host (e.g. { site: "ebay.com" }), returned as pointers. Do this as soon as you know the host you're about to drive; if one matches your task, load it by id. Returns a "no recipe" note when there's none.

  • { id: "" } — load a skill body: an in-house skill id (list below) OR a site recipe id host/slug from a site lookup.

Use the in-house skills below when you suspect the page exhibits a non-trivial mechanic but no SKILL block was auto-injected. The auto-injection heuristics are conservative; calling this tool is the explicit fallback.

Available in-house skills:

  • shadow-dom — deep selectors, iframe URL-pattern syntax, what works through deep-ref

  • cookie-consent — vendor-specific dismiss recipes (OneTrust, Cookiebot, Didomi, etc.)

  • modals — close-button heuristics, ESC handling, alertdialog vs. dialog

  • snapshot-misses — truncated/empty snapshots, image-rendered content

  • dynamic-content — choosing the right wait* method after async triggers

  • screenshots — when to screenshot vs. snapshot, scope and format choices

  • vision-fallback — click by coordinate when a "< " deep selector still can't surface the element (shadow DOM, nested iframe, canvas)

  • tabs — multi-tab workflows, peek-without-switching

  • autonomous-login — load before authenticating: when the user asked you to log in, when a wall blocks the task, or as soon as a password input appears. Covers the don't-login-by-default posture, contextual credential matching, MFA/captcha branches, and how to report the outcome.

  • autonomous-registration — load before creating an account: when the user asked you to sign up / register, or as soon as a Create-account form appears. Covers the don't-register-by-default posture, identity and credential-sink rules, save-first-then-loadSecret password handling, the emailed-code branch, and how to report the outcome.

  • captchas — the solve command, response semantics, escalation path (Cloud-only)

  • file-transfers — uploadFile / getDownloads, stdio-path vs. base64 content, size caps

  • profile-import — import the user's local Chrome/Brave/Edge sign-ins as a profile with the Browserless CLI (consent-gated; only when running on the user's machine)

Inputs: id, site, _prompt.

browserless_smartscraperA
Read-only
Inspect

Scrape a SINGLE webpage and return HTML, markdown, raw DOM text, links, screenshots, or PDFs plus page metadata, or AI-extracted JSON (formats "json" + jsonOptions) and a short summary (format "summary"); the AI formats add extraction units. Handles JavaScript-heavy pages and anti-bot measures automatically. For content across MULTIPLE pages of a site, use browserless_crawl; to list a site's URLs, use browserless_map.

Inputs: url (required), toDisk, _prompt, formats, +8 more.

browserless_usageA
Read-onlyIdempotent
Inspect

Read request and unit consumption for the Browserless account behind the current API token: successes, errors, timeouts, queueing, peak concurrency, captchas, proxy bytes and units. Use it to answer "how much have I used" or "why is my bill high". For per-request detail on failures, use browserless_logs instead. Read-only. MCP Apps clients receive a viewRef; call browserless_show with that exact reference to display the usage meter. Timeframe affects request counters only; billed units cover the billing period.

Inputs: _prompt, apiKeyIds, timeframe.

browserless_view_dataA
Read-onlyIdempotent
Inspect

Widget-only reader for a prepared replay. Not a rendering tool. Use the original viewRef and opaque cursor; never fetch replay data into the conversation.

Inputs: viewRef (required), cursor, _prompt, encoding. Returns: complete, nextCursor

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 21 tools

    Disambiguation2/5

    Several tools overlap heavily around page acquisition and automation: browserless_agent, browserless_function, browserless_smartscraper, browserless_export, and browserless_crawl can all fetch or drive a page, with boundaries that depend on subtle format or scale differences. The performance/result/run trio and show/view_data pair further split closely related operations, so an agent can easily choose the wrong entry point despite the detailed descriptions.

    Naming Consistency4/5

    All tools use the same browserless_ prefix and snake_case, with no camelCase or chaotic mixing. The main deviation is that some names are verbs (export, crawl, search, show) while others are nouns (agent, function, profiles, logs), but the pattern remains readable and predictable.

    Tool Count3/5

    At 21 tools the surface is heavy, sitting in the borderline 16-25 range, and several entries are narrow widget or payment helpers that could be consolidated. The breadth of the Browserless API partly justifies the count, but the set feels larger than necessary for most agent workflows.

    Completeness4/5

    The server covers a wide lifecycle: browser automation, scraping, crawling, mapping, search, export, performance audits, profiles, sessions, logs, usage, live viewing, and payment flows. Minor gaps remain, such as read-only session/profile management without stop or create/delete operations, but core browser automation workflows are well covered.

    Maintenance

    ActivityActive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      MCP server for browser automation with anti-detection. Scout pages, find elements, interact with websites, and monitor network traffic from any AI client that supports the Model Context Protocol.
      21
      1
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Remote MCP server for web scraping with anti-bot evasion. Provides stealth HTTP fetching, headless browser with Cloudflare bypass, CSS selectors, YouTube transcripts, and Markdown conversion.
      1
      MIT