Skip to main content
Glama

Browsa SDKs and MCP server

Official clients for Browsa, cloud browsers for AI agents. Each browser is Phantom, Browsa's own Chromium build.

PyPI npm browsa npm @browsa/mcp

Package

Install

Published at

Source

Python SDK

pip install browsa

PyPI: browsa

browsa-python

TypeScript SDK

npm i browsa

npm: browsa

browsa-ts

MCP server for Claude, Cursor and other MCP clients

npx -y @browsa/mcp

npm: @browsa/mcp

browsa-mcp

What you can do

  • Run an agent task. Describe the job in plain language and get JSON back. Use your own Anthropic, OpenAI or Google key, or a hosted tier ("llm": "browsa") with no key.

  • Drive a browser yourself. Start a cloud Chromium and connect Playwright or Puppeteer over CDP.

  • Scrape, extract or screenshot a page in one call.

  • Schedule a task and receive results on a signed webhook.

from browsa import Client

c = Client(api_key="agt_live_...")
job = c.run_task(task="Return the top 3 Hacker News stories as JSON", llm="browsa")
print(job.final_result)
import { Client } from "browsa";

const c = new Client({ apiKey: "agt_live_..." });
const job = await c.runTask({ task: "Return the top 3 Hacker News stories as JSON", llm: "browsa" });
console.log(job.finalResult);

New accounts get 100 free credits after email verification: no card, and credits never expire. Browsa does not supply proxies; you can bring your own HTTP, HTTPS or SOCKS5 proxy per browser.

Related MCP server: HumanBrowser

Issues

Bug reports and questions about the SDKs are welcome as GitHub issues in this repository. For account or billing questions, email support@browsa.io.

License

MIT. See each package's LICENSE file.

Available Tools

20 tools
actA

Perform one action in a browser started with start_browser and get back what changed (~ changed, + added, - removed), or a new view after a navigation. Input is sent as real mouse and key events. Name the element by id from observe, or by role and name, or click a point with x and y. The first line of the answer says failed, blocked, challenge or stale when the action did not go through. stale: the ids are from a view that no longer exists, nothing was done, and a new view follows.

Inputs: action (required), browser_id (required), x, y, +19 more.

cancel_jobA

Cancel a queued or running job. The job ends as failed with error_code CANCELLED and keeps its browser charge. A job that already finished returns an error with code JOB_NOT_CANCELLABLE.

Inputs: job_id (required).

create_scheduleA

Schedule a browser task to run automatically on a fixed interval (min 1 hour). Each run is a normal billed task. LLM key: same rules as run_task (the workspace's default saved key unless llm_key_id is given); the schedule stores only the saved key's id. With no llm and no saved key, the schedule runs on Browsa's hosted model and the result says so. Pass llm "browsa", "browsa-fast" or "browsa-smart" to choose a hosted tier.

Inputs: task (required), interval_seconds (required), llm, name, +6 more.

create_webhookA

Register a callback URL the platform will POST lifecycle events to (HMAC-SHA256 signed via X-Agents-Signature). Use the verify helper from browsa/webhooks in your receiver.

Inputs: url (required), events.

creditsA

Get the current credit balance + available top-up packs.

Inputs: no named parameters.

delete_webhookB

Delete (disable) a webhook subscription by id.

Inputs: webhook_id (required).

get_jobA

Fetch the current state of a previously-submitted job by UUID. Returns status (queued|running|completed|failed|input_required; a cancelled job is failed with error_code CANCELLED), step count, final_result text if terminal, and the live_url of the browser's live view while it runs. Cheap — call repeatedly to poll a long-running job started by run_task.

Inputs: job_id (required), wait_seconds.

list_browsersA

List this workspace's browsers (burners and saved identities) with their status.

Inputs: no named parameters.

list_identitiesA

List persistent browser identities (long-lived cookies/history/fingerprint, billed monthly). Use one in run_task via profile_id to reuse a warmed-up session — critical for sites that fingerprint cookie age, session continuity, or behavioral history (Akamai, Cloudflare-strict, DataDome).

Inputs: no named parameters.

list_job_filesA

List the output files a task wrote — extracted data + a session.gif recording. Returns name + size per file.

Inputs: job_id (required).

list_llm_keysA

List the LLM provider keys saved in this workspace: id, name, provider, masked key (prefix + last 4), whether it is the default for its provider, and its status (valid, invalid or unchecked). Never returns a secret. Pass an id as llm_key_id to run_task or create_schedule. Keys are added at https://app.browsa.io/dashboard/llm-keys.

Inputs: no named parameters.

list_modelsA

List the hosted tiers (browsa, browsa-fast, browsa-smart: the model each runs on, its default reasoning and credits per task) and the providers a saved or per-task LLM key can be for. Read-only and free.

Inputs: no named parameters.

list_schedulesA

List this workspace's scheduled tasks (id, task, interval, next run, run count). Secrets redacted.

Inputs: no named parameters.

list_webhooksA

List webhook subscriptions for this workspace.

Inputs: no named parameters.

observeA

Read the page of a browser started with start_browser, as compact text: one line per element, [id] role "name" state, inside a token budget. Use the ids with the act tool. No Playwright or CDP needed, and no extra charge. Ids stay valid across observe and act calls until the page loads a new document. On a full-page bot check nothing is read and the first lines say so.

Inputs: browser_id (required), tab, scope, budget, +1 more.

proxy_networkA

Say whether Browsa's built-in proxy network is enabled on this server and, when it is, list its tiers (datacenter, residential) with the exit countries of each and the price per GB in credits. Call this before passing proxy {"network": ...} to start_browser. When enabled is false, only your own proxy can be used.

Inputs: no named parameters.

respond_to_jobA

Answer an input_required prompt (CAPTCHA solution, human decision point). Flips the job back to running.

Inputs: job_id (required), response (required).

run_taskA

Run a browser-driven AI task on a fresh real Chromium burner. Returns the final result, the outcome and the total steps. status: completed only means the run ended: read outcome. outcome: failed with status: completed means the agent finished but could not do the task, and final_result says what stopped it. Use this when the user asks for anything web-shaped: scrape, fill, click, extract, login, place an order, search, summarize a page, etc. The browser is a real macOS-Chrome-fingerprinted Chromium with built-in CAPTCHA solving (Turnstile, hCaptcha, reCAPTCHA, ALTCHA, FunCaptcha) and behavioral humanization. Default timeout: 10 minutes.

Inputs: task (required), llm, country, max_steps, +7 more.

start_browserA

Start a real cloud browser and return its CDP URL, so you can drive it yourself with Playwright or Puppeteer (connect_over_cdp) instead of handing the work to run_task. Use this when you want to write the browser steps, or need the page open across several of your own tool calls. Billed per browser; always call stop_browser when you are done. Without a proxy the browser uses Browsa's data-center IP.

Inputs: ttl, proxy, country, os_type, +1 more.

stop_browserA

Stop a browser started with start_browser and release it. Always call this when finished; an unused browser keeps running until its ttl expires.

Inputs: browser_id (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 20 tools

    Disambiguation4/5

    The surface is split into clearly distinct clusters (managed jobs, self-driven browsers, identities, webhooks, schedules, billing), and descriptions explicitly contrast run_task vs start_browser and get_job vs list_job_files. Minor overlap remains between list_identities and list_browsers, and between create_schedule and run_task, but the descriptions resolve the boundaries well.

    Naming Consistency4/5

    Most names follow a clean snake_case verb_noun pattern (get_job, run_task, cancel_job, list_webhooks, create_webhook, delete_webhook, start_browser, stop_browser). A few outliers break the pattern: bare verbs observe and act, plus the noun phrases credits and proxy_network.

    Tool Count4/5

    At 20 tools this sits at the upper edge, but each tool maps to a genuinely distinct capability across jobs, browsers, schedules, webhooks and account data. Nothing looks duplicated or padded, though a couple of read-only helpers (list_models, credits, proxy_network) could plausibly be consolidated.

    Completeness3/5

    Core job lifecycle is well covered (run, poll, cancel, respond, list files) and browsers have start/stop/list. However there are real gaps: no tool to fetch the contents of files returned by list_job_files, no delete/get/update for schedules (only create and list), and webhooks lack a get/update operation.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables real browser automation as tools in Cursor, Claude Desktop, Windsurf, and any MCP-compatible client, allowing AI agents to interact with web pages through natural language.
      14 npm
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Cloud Chromium for AI agents — stealth, residential proxies, captcha solving, A2A 1.0 endpoint. The MCP server lets Claude Desktop, Cursor, and Cline drive a real browser via three tools (humanbrowser_run, humanbrowser_stream, humanbrowser_viewer_url).
      21
      Apache 2.0
    • A
      license
      A
      quality
      B
      maintenance
      Enables assistants such as Claude Code, Codex, and Gemini CLI to drive a real browser over MCP — navigating, clicking, typing, and reading live pages from plain-English instructions. Supports optional proxy routing, persistent profiles for surviving logins, and reproducible browser identities via seeds.
      18
      16
      32,523
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Turns YAML-defined browser flows into typed MCP tools that Claude, Cursor, VS Code and other MCP clients can call, letting agents run repeatable tasks like logins, form fills, report downloads, price checks and data extraction without letting them wander the page freely. Each call returns JSON output, downloaded files or screenshots, and failures report the step, error, page URL and a screenshot.
      19 npm
      MIT