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"
      }
    }
  }
}

Related MCP server: mcp-browser-use

Available Tools

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

Get an API Key

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

License

MIT