Browserbeam MCP Server

MCP (Model Context Protocol) server for Browserbeam — use real browser automation as tools in Cursor, Claude Desktop, Windsurf, and any MCP-compatible client.

Setup

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "browserbeam": {
      "command": "npx",
      "args": ["-y", "@browserbeam/mcp-server"],
      "env": {
        "BROWSERBEAM_API_KEY": "sk_live_your_key_here"
      }
    }
  }
}

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "browserbeam": {
      "command": "npx",
      "args": ["-y", "@browserbeam/mcp-server"],
      "env": {
        "BROWSERBEAM_API_KEY": "sk_live_your_key_here"
      }
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "browserbeam": {
      "command": "npx",
      "args": ["-y", "@browserbeam/mcp-server"],
      "env": {
        "BROWSERBEAM_API_KEY": "sk_live_your_key_here"
      }
    }
  }
}

Available Tools

Tool	Description
browserbeam_create_session	Create a browser session, optionally navigate to a URL
browserbeam_navigate	Navigate to a new URL in an existing session
browserbeam_observe	Get page content as markdown or HTML with interactive element refs. Supports mode: "full" for all sections and include_page_map for a structural map
browserbeam_click	Click an element by ref, text, or label
browserbeam_fill	Fill form fields or an entire form at once
browserbeam_type	Type text character-by-character with real keyboard events
browserbeam_select	Select an option from a dropdown
browserbeam_check	Check or uncheck a checkbox or radio button
browserbeam_scroll	Scroll the page or scroll an element into view
browserbeam_scroll_collect	Scroll the entire page to load lazy content, then observe
browserbeam_wait	Wait for a selector, text, JS expression, or fixed delay
browserbeam_extract	Extract structured data using a declarative schema
browserbeam_execute_js	Run custom JavaScript in the browser page context
browserbeam_screenshot	Take a screenshot of the current page
browserbeam_pdf	Generate a PDF of the current page
browserbeam_upload	Upload files to a file input element
browserbeam_list_sessions	List your sessions; optional status filter: active, closed, or failed
browserbeam_get_session	Get the status, duration, and error fields (e.g. error_code / error_message when status is failed) for a session
browserbeam_close	Close a session and release resources

Page Map & Full Mode

The first observe in every session auto-includes a page map — a lightweight outline of page sections (nav, header, main, aside, footer) with CSS selectors and content hints. This lets agents discover what's on the page beyond the main content area without spending tokens.

To get content from all page sections instead of just the main area, use mode: "full":

{
  "tool": "browserbeam_observe",
  "params": {
    "session_id": "ses_abc123",
    "mode": "full",
    "max_text_length": 20000
  }
}

The response organizes content by section:

## [nav]
Home | Products | About | Contact

## [main]
# Welcome to Our Site
...main content...

## [aside]
Related links, sidebar widgets...

## [footer]
© 2026 Company | Privacy | Terms

Use include_page_map: true to re-request the page map on subsequent observations.

Proxies

All sessions use a datacenter proxy by default (country auto-detected from the URL's TLD). To customize, pass proxy_kind and/or proxy_country to browserbeam_create_session:

{
  "tool": "browserbeam_create_session",
  "params": {
    "url": "https://example.com",
    "proxy_kind": "residential",
    "proxy_country": "us"
  }
}

AI-Powered Selectors

Use the ai >> prefix in extract schemas to describe fields in plain English. The engine resolves them to CSS selectors via AI and caches the result:

{
  "tool": "browserbeam_extract",
  "params": {
    "session_id": "ses_abc123",
    "schema": {
      "_parent": "article.product_pod",
      "name": "ai >> the product title",
      "price": "ai >> the price including currency symbol"
    }
  }
}

Agent guidelines (for AI clients)

• Close sessions: Agents should call browserbeam_close when finished with a session so resources are released and credit consumption stops. Only keep a session open if the user explicitly needs continued work on the same browser.
• Page discovery: The first observe auto-includes a map. Check it before using mode: "full" — if the info you need is in the main content, default mode is more token-efficient.
• Full mode: Use mode: "full" when you need sidebar content, footer links, or navigation items that aren't in the main area. Default max_text_length for full mode is 20,000 characters.
• Truncation: Page markdown is capped by default at 12,000 characters (browserbeam_observe and the page payload from browserbeam_create_session / browserbeam_navigate). If output is truncated, use browserbeam_observe with a higher max_text_length or browserbeam_scroll_collect (default 100,000 characters) for long or lazy-loaded pages.

How It Works

The MCP server translates tool calls into Browserbeam API requests. Your AI agent sees structured page data (markdown content, interactive element refs, change diffs) instead of raw HTML.

AI Agent → MCP Tool Call → Browserbeam API → Real Browser → Structured Response → AI Agent

Environment Variables

Variable	Required	Description
BROWSERBEAM_API_KEY	Yes	Your Browserbeam API key (sk_live_...)
BROWSERBEAM_BASE_URL	No	API base URL (default: https://api.browserbeam.com)

Get an API Key

Sign up at browserbeam.com — 5,000 free credits, no credit card required.

License

MIT