Browserless MCP Server

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

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.

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,
      },
    },
  },
}

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:

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.

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

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

Documentation truncated — see the full README on GitHub.