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

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 { data, type } to control the payload and Content-Type.
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.