Skip to main content
Glama
browserless

browserless-mcp

Official
by browserless
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

browserless_function

Destructive

Execute custom Puppeteer code in Browserless cloud to handle complex scraping, form filling, or custom browser automation. Return data with content type for binary or text responses.

Instructions

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.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
codeYesJavaScript (ESM) code to execute. The default export receives { page, context } and should return { data, type } where data is the response payload and type is the Content-Type string.
_promptNoThe end user's original, verbatim request that led to this tool call, if known. Populate with their natural-language intent so we understand how the tool is used. Do NOT include secrets, passwords, API keys, tokens, or other credentials. Omit if unavailable.
contextNoOptional context object passed to the function as the second argument.
profileNoOptional name of an authentication profile to hydrate into the browser before the function executes. The profile's cookies, localStorage, and IndexedDB are restored into the session before the request runs. The profile must already exist for the API token in use — create one with Browserless.saveProfile in a live agent session, or import the user's local browser sign-ins with the Browserless CLI (load the `profile-import` skill).
timeoutNoRequest timeout in milliseconds

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv1.39.0
    • changedInput schema / properties / profile / description
      Previous value: -"Optional name of an authentication profile to hydrate into the browser before the function executes. The profile's cookies, localStorage, and IndexedDB are restored into the session before the request runs. The profile must already exist for the API token in use — create one with Browserless.saveProfile in a live agent session first."New value: +"Optional name of an authentication profile to hydrate into the browser before the function executes. The profile's cookies, localStorage, and IndexedDB are restored into the session before the request runs. The profile must already exist for the API token in use — create one with Browserless.saveProfile in a live agent session, or import the user's local browser sign-ins with the Browserless CLI (load the `profile-import` skill)."
  2. Changed1 schema field changedv1.34.0
    • changedInput schema / properties / context / additionalProperties
      Previous value: -falseNew value: +{}
  3. First observedv1.16.0

TDQS

A4.5/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare destructive/openWorld, but the description adds substantial behavior the structured fields do not: the return contract shape, how MIME types map to vision/audio/resource content blocks, and the hard 200,000-character text cap with token estimates and remediation advice. This is exactly the non-obvious operational context an agent needs to avoid a failed call.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded purpose followed by a scannable bulleted list of MIME-type outcomes and a clear size-limit sentence. Slightly long, but every section carries operational value rather than filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the return-value burden and does so well (data/type contract, content-block mapping, size limits). Minor gaps remain around error behavior and execution-duration expectations, though timeout is covered in the schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description goes further by explaining what the function receives (page, context) and what MIME values produce in the response, adding semantics the schema's terse descriptions don't convey. It does not add much about timeout or profile beyond what the schema already states.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Names a specific verb and resource ('Execute custom Puppeteer JavaScript code on the Browserless cloud') and describes the exact execution contract (function receives page + context, returns {data, type}). The closing sentence ('complex scraping, form filling, or any browser automation that requires custom code') positions it as the low-level escape hatch relative to higher-level siblings like smartscraper and crawl.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear when-to-use guidance: custom code for complex scraping, form filling, or automation not covered by prebuilt flows. It does not explicitly name which sibling to prefer first (e.g., smartscraper), so the routing decision is implied rather than stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools