@mindstone/mcp-server-browserbase

Cloud browser automation via the Browserbase API: sessions with live-view debugging, AI web agents, persistent contexts, downloads, fetch/search, and serverless functions.

Best for MCP hosts that want a local browser-automation connector covering the entire Browserbase API — from "open a browser and show me" to "run an agent that extracts pricing data".

Status

• Version: 0.1.1 · npm
• Auth: API key (BROWSERBASE_API_KEY)
• Tools: 53 (projects, sessions, contexts, agents, agent runs, downloads, extensions, certificates, fetch/search, functions)
• Surface: cloud-api
• Machine-readable: STATUS.json

Why this exists

Browserbase's API spans everything from raw CDP sessions to fully-managed AI agents. This package exposes all of it to local stdio MCP hosts as a single connector with deliberate guardrails: session billing is called out in tool descriptions, destructive actions are annotated, external web content is always wrapped as untrusted data, and long-running work is polled (Browserbase has no webhooks).

Example interaction

"Extract the pricing tiers from example.com and give them to me as JSON."

Tools the host calls:

1. create_agent_run — starts a run with the task and a result_schema for the JSON shape.
2. wait_for_agent_run — polls until the run completes and returns the structured result.
3. get_agent_run_messages — (optional) shows what the agent did, step by step.

Response (trimmed):

{
  "ok": true,
  "runId": "r0a0b0c0-…",
  "status": "COMPLETED",
  "result": { "plans": [ { "name": "…", "price": 0 } ] },
  "waited_seconds": 47
}

Requirements

• Node.js 20+
• npm
• A Browserbase API key (browserbase.com/settings).

One-click install

After clicking the button, your host will prompt you to fill: BROWSERBASE_API_KEY.

{
  "mcpServers": {
    "Browserbase": {
      "command": "npx",
      "args": [
        "-y",
        "@mindstone/mcp-server-browserbase"
      ],
      "env": {
        "BROWSERBASE_API_KEY": ""
      }
    }
  }
}

Quick Start

Install & build

cd <path-to-repo>/connectors/browserbase
npm install
npm run build

npx

npx -y @mindstone/mcp-server-browserbase

Local

node dist/index.js

Configuration

When running inside a host that provides the credential bridge, configure_browserbase_api_key persists the key through the host instead of the environment.

MCP Host Configuration

{
  "mcpServers": {
    "browserbase": {
      "command": "npx",
      "args": ["-y", "@mindstone/mcp-server-browserbase"],
      "env": {
        "BROWSERBASE_API_KEY": "your-api-key"
      }
    }
  }
}

Security notes

Sessions are billed — release them

Every create_session starts a billable browser (per-minute, 1-minute minimum). The create_session and end_session descriptions tell the agent this explicitly, and end_session should be called as soon as automation finishes. Exceeding the project's concurrency limit returns 429 with a retry-after window that the error resolution surfaces verbatim.

Live-view URLs grant control

get_session returns a credentialed connectUrl and get_session_debug_urls returns debugger/live-view URLs. Anyone with these URLs can watch AND drive the browser — they are for sharing with the session's owner, never publicly.

External content is always enveloped

Anything authored outside your account — fetched page content, search results, page titles in debug URLs, agent run tasks/results/messages, CDP log bodies, replay playlists, download filenames, function output, error details — is wrapped in <untrusted-content source="browserbase:…"> envelopes with close-tag breakout escaping before it reaches the model. CDP log rawBody values are additionally truncated beyond ~4KB with a truncation note.

File uploads are workspace-sandboxed

upload_session_file, upload_extension, and upload_certificate accept local file_paths. Reads are constrained to MCP_WORKSPACE_PATH (or the system temp directory when unset) using canonical-prefix containment: .. traversal, absolute paths outside the sandbox, and symlinks that escape it are rejected before any disk read. The read is open-then-validate: the connector opens a descriptor, confirms the opened inode is the file the sandbox approved, reads through that descriptor, and re-checks it after the read — a file swapped or modified mid-read fails closed.

fetch_url cannot probe internal networks

fetch_url (and the URLs embedded in search results you might fetch next) are guarded by a public-URL check: only http:///https:// schemes, and localhost, loopback, link-local, and private IP ranges are rejected before any request is sent.

Delete and stop tools are annotated as destructive

delete_context, delete_agent, delete_download, delete_extension, delete_certificate, end_session, stop_agent_run, invoke_function, and all create_*/upload_* tools carry destructiveHint: true. Deletes are permanent; hosts should require explicit user confirmation.

Tools (53)

Configuration

• configure_browserbase_api_key — Save your Browserbase API key (host-persisted when a bridge is present)

Projects

• list_projects — List projects (IDs, concurrency limits, default timeouts)
• get_project — Get one project's details
• get_project_usage — Browser minutes and proxy bytes consumed

Sessions

• create_session — Create a cloud browser session (billed per minute; returns connectUrl)
• list_sessions — List sessions, filtered by status or userMetadata query
• get_session — Get a session's status and connectUrl
• end_session — Release a session (REQUEST_RELEASE semantics; sessions also auto-expire)
• get_session_debug_urls — Live-view + debugger URLs to share with a human
• get_session_logs — CDP-level session logs (raw bodies truncated beyond ~4KB)
• get_session_replays — List recorded pages available for replay
• get_session_replay_playlist — Fetch a page's m3u8 replay playlist
• request_session_recording_downloads — Request async MP4 assembly (HTTP 202)
• get_session_recording_downloads — Poll MP4 status; get short-lived signed URLs
• upload_session_file — Upload a sandboxed local file to /tmp/.uploads/ in the session

Contexts (persistent browser state)

• create_context — Create a context for persisting cookies/storage across sessions
• get_context — Get a context's details
• delete_context — Permanently delete a context

Agents

• create_agent — Create a reusable agent (name, system prompt, result schema)
• list_agents — List agents (cursor-paginated, date-filterable)
• get_agent — Get an agent's prompt and result schema
• update_agent — Partially update an agent
• delete_agent — Delete an agent (existing runs unaffected)

Agent Runs

• create_agent_run — Start a run (ad-hoc or with an agent; %variable% substitution for sensitive values)
• list_agent_runs — List runs (cursor-paginated, filterable)
• get_agent_run — Get a run's status and terminal result/cause
• wait_for_agent_run — Recommended: poll until terminal and return the result
• get_agent_run_messages — The run's UIMessage conversation (since/nextSince feed)
• stop_agent_run — Stop a running run (202; 409 if already terminal)

Downloads (files downloaded inside sessions)

• list_downloads — List downloads for a session (offset-paginated, filterable)
• get_download_info — Metadata (size, checksum, MIME type)
• get_download_file — Fetch the bytes as base64 (8MB inline cap)
• delete_download — Permanently delete a download

Extensions

• upload_extension — Upload a zipped Chrome extension (sandboxed file read)
• get_extension — Get an uploaded extension
• delete_extension — Permanently delete an extension

Certificates

• upload_certificate — Upload a CA certificate for TLS-inspecting proxies
• list_certificates — List uploaded certificates
• get_certificate — Get a certificate
• delete_certificate — Permanently delete a certificate

Fetch & Search

• fetch_url — Server-side fetch: raw body, markdown, or schema-driven JSON
• web_search — Web search with ranked results

Functions (serverless browser automations — list/invoke/inspect only)

• list_functions — List deployed functions
• get_function — Get a function
• invoke_function — Invoke a function (async 202; poll the invocation)
• list_function_versions — List a function's versions
• get_function_version — Get a version's userParamsSchema (check before invoking)
• list_function_invocations — List a version's invocations
• get_function_invocation — Get an invocation's status, results, and cause
• get_function_invocation_logs — An invocation's logs
• list_function_builds — List function builds
• get_function_build — Get a build's status and failure cause
• get_function_build_logs — A build's logs

API coverage notes

• Deprecated upstream: GET /sessions/{id}/recording (rrweb event dump) is deprecated by Browserbase and returns a deprecation 404 — it is deliberately not exposed. Use get_session_replays / get_session_replay_playlist (watchable) or the recording-download tools (MP4 files) instead.
• No webhooks: Browserbase is poll-based. Agent runs (wait_for_agent_run / get_agent_run), recording downloads (get_session_recording_downloads), and function invocations (get_function_invocation) are all polled.
• No list endpoints for contexts or extensions — record the IDs returned at creation.
• Functions are deploy-only via the Browserbase CLI — this connector lists, inspects, and invokes existing functions; it cannot create them.

Error handling

All upstream errors are returned as structured JSON with ok: false, a semantic code (AUTH_REQUIRED, VALIDATION_FAILED, NOT_FOUND, CONFLICT, GONE, RATE_LIMITED, PAYMENT_REQUIRED, UPSTREAM_ERROR, TIMEOUT, …), and an actionable resolution. Rate-limit errors include the server-provided retry-after window. Upstream error text is enveloped as untrusted content, and the API key never appears in any output.

Licence

FSL-1.1-MIT — Functional Source License, Version 1.1, with MIT future licence. The software converts to MIT licence on 2030-04-08.