Ermöglicht es AI Agents, Web Scraping, Browser-Automatisierung, Site Crawling und Lighthouse-Performance-Audits über die Browserless API durchzuführen.
Auch bekannt als browserless/browserless-mcp, browserless-mcp, @browserless.io/mcp
- Stars
- 19
- Tools
- 21
- Downloads, 30 Tage
- 15.384
- Neueste Version
- 1.48.0
- Letzter Commit
- 13. Nov. 2026
- Lizenz
- —
Was ist Browserless MCP?
Ermöglicht es AI Agents, Web Scraping, Browser-Automatisierung, Site Crawling und Lighthouse-Performance-Audits über die Browserless API durchzuführen. Er stellt 21 Tools bereit, etwa browserless_show, browserless_view_data, browserless_export.
Zusammenfassung generiert aus dem README des Projekts
Über Browserless MCP server
Browserless bietet einen MCP server an, der AI Clients wie Claude Desktop, Cursor und Windsurf mit der Browserless.io API verbindet. Dieses Setup erlaubt es Entwicklern, komplexe Web-Automatisierung und Datenextraktion durchzuführen, ohne lokale Browser-Abhängigkeiten installieren zu müssen. Nutzer verbinden sich, indem sie einen API-Token über eine gehostete URL in ihrer Client-Config angeben.
Der Server enthält eine breite Palette spezialisierter Tools für die Interaktion mit dem Web. Du kannst browserless_smartscraper nutzen, um Markdown oder JSON aus JavaScript-lastigen Seiten zu extrahieren, oder browserless_crawl, um ganze Websites mit Tiefensteuerung zu navigieren. Für Performance-Tests führt browserless_performance Lighthouse-Audits durch und liefert Scores für die einzelnen Kategorien zurück. Der Server unterstützt zudem fortgeschrittene Automatisierung über browserless_agent, das einen ReAct-Loop nutzt, um Klicks, Tippen und Scrollen zu handhaben, sowie browserless_function zur Ausführung von eigenem Puppeteer JavaScript Code.
Über einfaches Scraping hinaus verwaltet der Server die Authentifizierung über browserless_profiles und bietet tiefe Einblicke in die Operationen. Du kannst den Verbrauch mit browserless_usage überwachen, aktive Sessions inspizieren oder Fehler mit browserless_logs diagnostizieren. Er unterstützt sogar das Betrachten von Session-Replays und Screenshots direkt innerhalb kompatibler MCP Apps Clients.
Was du damit machen kannst
- 1Automatisierte Web-DatenextraktionExtrahiere strukturierte JSON- oder Markdown-Inhalte von Websites, die starkes JavaScript oder Anti-Bot-Schutz nutzen.
- 2Mapping der Website-StrukturEntdecke alle verfügbaren URLs auf einer spezifischen Domain, indem du Sitemaps scannst und Links extrahierst.
- 3Web-Performance-AuditingFühre Lighthouse-Audits auf einer URL aus, um Kategorie-Scores und detaillierte Performance-Reports zu erhalten.
- 4Autonome Browser-InteraktionSteuere einen AI Agent an, um Websites durch Klicken, Tippen und Scrollen innerhalb einer persistenten Session zu navigieren.
Geschrieben aus dem README des Projekts. Jeder Use Case wurde gegen ein Zitat daraus geprüft.
So installierst du Browserless MCP
Formate geprüft am 10. Nov. 2026Zu Cursor hinzufügenZu Goose hinzufügenBrowserless MCP in Claude Code installieren
$ claude mcp add --env 'BROWSERLESS_TOKEN=<YOUR_BROWSERLESS_TOKEN>' browserless-mcp -- npx -y @browserless.io/mcpBrowserless MCP in Cursor installieren
~/.cursor/mcp.json
{
"mcpServers": {
"browserless-mcp": {
"command": "npx",
"args": [
"-y",
"@browserless.io/mcp"
],
"env": {
"BROWSERLESS_TOKEN": "<YOUR_BROWSERLESS_TOKEN>"
}
}
}
}Browserless MCP in VS Code installieren
.vscode/mcp.json
{
"servers": {
"browserless-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@browserless.io/mcp"
],
"env": {
"BROWSERLESS_TOKEN": "<YOUR_BROWSERLESS_TOKEN>"
}
}
}
}Browserless MCP in VS Code CLI installieren
$ code --add-mcp '{"name":"browserless-mcp","type":"stdio","command":"npx","args":["-y","@browserless.io/mcp"],"env":{"BROWSERLESS_TOKEN":"<YOUR_BROWSERLESS_TOKEN>"}}'Browserless MCP in Claude Desktop installieren
claude_desktop_config.json
{
"mcpServers": {
"browserless-mcp": {
"command": "npx",
"args": [
"-y",
"@browserless.io/mcp"
],
"env": {
"BROWSERLESS_TOKEN": "<YOUR_BROWSERLESS_TOKEN>"
}
}
}
}Browserless MCP in Codex installieren
$ codex mcp add browserless-mcp --env 'BROWSERLESS_TOKEN=<YOUR_BROWSERLESS_TOKEN>' -- npx -y @browserless.io/mcpBrowserless MCP in Codex config.toml installieren
~/.codex/config.toml
[mcp_servers.browserless-mcp] command = "npx" args = ["-y", "@browserless.io/mcp"] [mcp_servers.browserless-mcp.env] BROWSERLESS_TOKEN = "<YOUR_BROWSERLESS_TOKEN>"
Browserless MCP in Gemini CLI installieren
$ gemini mcp add -s user -e 'BROWSERLESS_TOKEN=<YOUR_BROWSERLESS_TOKEN>' browserless-mcp npx -- -y @browserless.io/mcpBrowserless MCP in Gemini settings.json installieren
~/.gemini/settings.json
{
"mcpServers": {
"browserless-mcp": {
"command": "npx",
"args": [
"-y",
"@browserless.io/mcp"
],
"env": {
"BROWSERLESS_TOKEN": "<YOUR_BROWSERLESS_TOKEN>"
}
}
}
}Von HostedMCP gestartet am 16. Nov. 2026
Wir haben diesen Befehl für @browserless.io/mcp 1.48.0 in einem isolierten Container ohne Netzwerk und ohne Schlüssel ausgeführt. Er hat geantwortet und 21 Tools gelistet.
Browserless MCP tools 21
Vom Server mit tools/list gelesenbrowserless_showNur lesendDisplay 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.
browserless_view_dataNur lesendWidget-only reader for a prepared replay. Not a rendering tool. Use the original viewRef and opaque cursor; never fetch replay data into the conversation.
browserless_exportNur lesendExport 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.
browserless_skillNur lesendLoad a Browserless agent skill on demand, or discover site-specific recipes. Two uses: - **{ site: "<host>" }** — 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: "<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)
browserless_agentAktionREAD CAREFULLY: Execute browser commands in an agent session. ## Core Loop (ReAct: Reason → Act → Observe) 0. **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`. 1. **goto** — waits "domcontentloaded" 2. **snapshot** — returns interactive + informational elements (button, link, textbox, combobox, checkbox, heading, img+alt) with ref= selectors 3. **Plan** all actions from snapshot 4. **Batch** execute 5. **Re-snapshot** only if page changed 6. 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 whe
browserless_performanceNur lesendRun 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. Use the local path (stdio) or download URL (HTTP) to 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.
browserless_performance_runNur lesendWidget-only execution of a prepared Lighthouse audit. Repeated requests reuse the same audit.
browserless_performance_resultNur lesendRetrieve 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.
browserless_accountNur lesendRead 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.
browserless_usageNur lesendRead 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.
browserless_sessionsNur lesendInspect 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.
browserless_logsNur lesendRead 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.
| browserless_show | 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. | Nur lesend |
| browserless_view_data | 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. | Nur lesend |
| browserless_export | 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. | Nur lesend |
| browserless_skill | Load a Browserless agent skill on demand, or discover site-specific recipes. Two uses: - **{ site: "<host>" }** — 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: "<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) | Nur lesend |
| browserless_agent | READ CAREFULLY: Execute browser commands in an agent session. ## Core Loop (ReAct: Reason → Act → Observe) 0. **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`. 1. **goto** — waits "domcontentloaded" 2. **snapshot** — returns interactive + informational elements (button, link, textbox, combobox, checkbox, heading, img+alt) with ref= selectors 3. **Plan** all actions from snapshot 4. **Batch** execute 5. **Re-snapshot** only if page changed 6. 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 whe | Aktion |
| browserless_performance | 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. Use the local path (stdio) or download URL (HTTP) to 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. | Nur lesend |
| browserless_performance_run | Widget-only execution of a prepared Lighthouse audit. Repeated requests reuse the same audit. | Nur lesend |
| browserless_performance_result | 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. | Nur lesend |
| browserless_account | 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. | Nur lesend |
| browserless_usage | 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. | Nur lesend |
| browserless_sessions | 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. | Nur lesend |
| browserless_logs | 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. | Nur lesend |
Alle 21 Tools anzeigenWeniger Tools anzeigen
browserless_smartscraperNur lesendScrape 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.
browserless_functionAktionExecute custom Puppeteer JavaScript code on the Browserless cloud. Your function receives a Puppeteer `page` object and optional `context` data. Return { data, type } to control the response payload and Content-Type. For binary outputs, set `type` to a real MIME so the bytes come back as a proper content block instead of base64 text: - `image/png` / `image/jpeg` / `image/webp` → vision content block (~1.5K tokens) - `audio/mpeg` / `audio/wav` → audio content block - `application/pdf` and other binaries → resource content block (attachment) Text responses are capped at 200,000 characters (~50K tokens). Larger text payloads will be rejected — filter or summarize inside your function, or switch to a binary type if you actually meant to return bytes. Useful for complex scraping, form filling, or any browser automation that requires custom code.
browserless_mapNur lesendDiscover 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.
browserless_crawlNur lesendCrawl 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.
browserless_live_urlAktionCreate, 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.
browserless_profilesNur lesendList 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.
browserless_searchNur lesendSearch the web using Browserless and optionally scrape each result. Performs web searches via SearXNG and can return results from web, news, or images. Optionally scrape each result URL to get markdown, HTML, links, or screenshots. Useful for research, gathering information, and finding relevant web pages.
browserless_link_connectAktionManage the Browserless Stripe Link wallet. Use action "status" to check availability; it never returns a URL. Use "connect" to mint a Stripe-owned authorization URL to give the user, or "disconnect" to remove the connection. When "status" is not_connected, call "connect" to obtain that URL — the status instruction alone has no link. Never ask the user for raw card details.
browserless_link_checkoutAktionCreate, resume, cancel, or report a Stripe Link checkout in the exact active browser session. Create requires the latest browserless_agent sessionId. Pass payment-field deep selectors whenever a card form is shown, including Stripe-hosted checkout; omit them only for a pure Link Pay Token handoff. Resume retrieves and fills only after Link approval; payment credentials never reach this tool.
| browserless_smartscraper | 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. | Nur lesend |
| browserless_function | Execute custom Puppeteer JavaScript code on the Browserless cloud. Your function receives a Puppeteer `page` object and optional `context` data. Return { data, type } to control the response payload and Content-Type. For binary outputs, set `type` to a real MIME so the bytes come back as a proper content block instead of base64 text: - `image/png` / `image/jpeg` / `image/webp` → vision content block (~1.5K tokens) - `audio/mpeg` / `audio/wav` → audio content block - `application/pdf` and other binaries → resource content block (attachment) Text responses are capped at 200,000 characters (~50K tokens). Larger text payloads will be rejected — filter or summarize inside your function, or switch to a binary type if you actually meant to return bytes. Useful for complex scraping, form filling, or any browser automation that requires custom code. | Aktion |
| browserless_map | 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. | Nur lesend |
| browserless_crawl | 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. | Nur lesend |
| browserless_live_url | 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. | Aktion |
| browserless_profiles | 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. | Nur lesend |
| browserless_search | Search the web using Browserless and optionally scrape each result. Performs web searches via SearXNG and can return results from web, news, or images. Optionally scrape each result URL to get markdown, HTML, links, or screenshots. Useful for research, gathering information, and finding relevant web pages. | Nur lesend |
| browserless_link_connect | Manage the Browserless Stripe Link wallet. Use action "status" to check availability; it never returns a URL. Use "connect" to mint a Stripe-owned authorization URL to give the user, or "disconnect" to remove the connection. When "status" is not_connected, call "connect" to obtain that URL — the status instruction alone has no link. Never ask the user for raw card details. | Aktion |
| browserless_link_checkout | Create, resume, cancel, or report a Stripe Link checkout in the exact active browser session. Create requires the latest browserless_agent sessionId. Pass payment-field deep selectors whenever a card form is shown, including Stripe-hosted checkout; omit them only for a pure Link Pay Token handoff. Resume retrieves and fills only after Link approval; payment credentials never reach this tool. | Aktion |
Konfiguration
BROWSERLESS_TOKENErforderlichSecretYour Browserless API token
BROWSERLESS_API_URLBrowserless API endpoint (regional or self-hosted)
BROWSERLESS_PUBLIC_URL
| Name | Beschreibung | Typ |
|---|---|---|
| BROWSERLESS_TOKEN | Your Browserless API token | ErforderlichSecret |
| BROWSERLESS_API_URL | Browserless API endpoint (regional or self-hosted) | |
| BROWSERLESS_PUBLIC_URL | — |
Automatisierte Checks
Geluften am 16. Nov. 2026Vollständiger Bericht →Unsere automatisierten Checks bestanden. Das ist kein Security-Audit: Lies den Code und gib dem Server nur den minimal notwendigen Zugriff. Wie die Checks funktionieren · Was du für mehr Punkte verbessern kannst
- Source Repository verknüpft und erreichbarbrowserless/browserless-mcp is public and reachablegithub.com/browserless/browserless-mcp ↗Bestanden
- Paket nennt dieses Repository als Quelle@browserless.io/mcp names browserless/browserless-mcp as sourcenpmjs.com/package/@browserless.io/mcp ↗Bestanden
- Build-Provenienz (Sigstore-Attestierung)Sigstore attestation for @browserless.io/mcpnpmjs.com/package/@browserless.io/mcp/v/1.48.0#provenance ↗Bestanden
- Open Source Lizenz (OSI)No licenseBefund
- Commit oder Release im letzten JahrLast commit or release 2026-11-13github.com/browserless/browserless-mcp ↗Bestanden
- OpenSSF ScorecardNicht geprüft
- Package-Name ähnelt keinem populären PackageNo popular package one edit away from @browserless.io/mcpBestanden
- Keine kritischen Advisories im Paket oder seinen Abhängigkeitenthe package checked; no critical advisoryosv.dev ↗Bestanden
- Keine versteckten Anweisungen an das Modell21 tool descriptions and the README read; no override phrases, credential paths or hidden charactersBestanden
- Destruktive Tools sind markiertNo tool named like delete, drop or execBestanden
- Remote-Endpoint beantwortet den MCP-HandshakeHTTPS endpoint answered 401 (sign-in required)Bestanden
README
Auf GitHub ansehenBrowserless 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.
Browserless MCP Fragen
Wie füge ich Browserless MCP zu Claude Code hinzu?
Führe claude mcp add --env 'BROWSERLESS_TOKEN=<YOUR_BROWSERLESS_TOKEN>' browserless-mcp -- npx -y @browserless.io/mcp in deinem Terminal aus. Füge --scope user hinzu, damit der Server in jedem Projekt verfügbar ist.
Wie füge ich Browserless MCP zu Cursor hinzu?
Öffne ~/.cursor/mcp.json und füge den Server unter mcpServers hinzu, mit der Cursor-Config aus dem Installationsabschnitt oben.
Welche Tools bietet Browserless MCP?
Er stellt 21 Tools bereit, darunter browserless_show, browserless_view_data, browserless_export, browserless_skill, browserless_agent.
Kann der Server mit JavaScript-lastigen Websites umgehen?
Ja, das smart scraper Tool verarbeitet JavaScript-lastige Seiten und Anti-Bot-Maßnahmen automatisch.
Was kann ich mit dem browserless_agent Tool machen?
Es erlaubt dir, eine persistente Browser-Session mittels eines ReAct-Loops zu steuern, inklusive Multi-Tab-Workflows, Screenshots und Captcha-Lösung.
Wie lange sind die Lighthouse-Report-Dateien gültig?
Die Dateien laufen nach 15 Minuten ab oder sobald die MCP-Session endet.