Browserbase MCP Server Setup

Quick Installation

Install with Cursor

One-click installation directly in Cursor

You can also add Browserbase MCP to Claude Code with a single command. If your client supports HTTP request headers, prefer Authorization: Bearer YOUR_BROWSERBASE_API_KEY; otherwise, use the legacy query-parameter fallback:

claude mcp add --transport http browserbase "https://mcp.browserbase.com/mcp?browserbaseApiKey=YOUR_BROWSERBASE_API_KEY"

We support both local STDIO and hosted Streamable HTTP (SHTTP). We recommend hosted Streamable HTTP for most users.

Endpoint

Hosted Streamable HTTP endpoint (served on Browserbase infrastructure):

https://mcp.browserbase.com/mcp

Prerequisites

Get your Browserbase credentials

Get your Browserbase API key from the Browserbase Dashboard.

Then copy your API Key directly from the input.

Authentication and Query Parameters (Hosted Streamable HTTP)

Required for tool calls

Authorization

Pass your Browserbase API key as an HTTP authorization header: Authorization: Bearer YOUR_BROWSERBASE_API_KEY.

The hosted server also accepts x-bb-api-key: YOUR_BROWSERBASE_API_KEY. The browserbaseApiKey query parameter remains supported as a deprecated compatibility fallback for clients that cannot set request headers.

Optional

Query Param	Type	Behavior
`modelName`	string	Defaults to `google/gemini-2.5-flash-lite`
`modelApiKey`	string	Required when `modelName` is non-default
`keepAlive`	boolean string	`"true"` or `"false"`
`proxies`	boolean string	`"true"` or `"false"`
`verified`	boolean string	`"true"` or `"false"`

Boolean query values must be exact strings: "true" or "false".

Available Tools

navigate

Navigate to any URL in the browser

url

string

required

The URL to navigate to

act

Perform an action on the web page using natural language

action

string

required

The action to perform (e.g., “click the login button”, “fill form field”)

observe

Observe and find actionable elements on the page.

instruction

string

required

Specific instruction for observation (e.g., “find the login button”, “locate search form”)

extract

Extract data from the current page.

instruction

string

Optional extraction instruction.

start

Create or reuse a Browserbase session and set it as active for the current MCP transport session.

No input parameters required.

sessionId

string

Browserbase session ID.

end

Close the active Browserbase session for the current MCP transport session.

No input parameters required.

Local Command-Line Flags

Command-line flags are only available when running the server locally (npx @browserbasehq/mcp with flags or local development setup).

Flag	Description
`--proxies`	Enable Browserbase proxies for the session
`--verified`	Enable Browserbase Verified Identity (Scale Plan only)
`--keepAlive`	Enable Browserbase Keep Alive Session
`--contextId <contextId>`	Specify a Browserbase Context ID to use
`--persist [boolean]`	Whether to persist the Browserbase context (default: true)
`--port <port>`	Port to listen on for HTTP or Streamable HTTP transport
`--host <host>`	Host to bind server to (default: localhost, use 0.0.0.0 for all interfaces)
`--browserWidth <width>`	Browser viewport width (default: 1024)
`--browserHeight <height>`	Browser viewport height (default: 768)
`--modelName <model>`	The model to use for Stagehand (default: google/gemini-2.5-flash-lite)
`--modelApiKey <key>`	API key for the custom model provider (required when using custom models)
`--experimental`	Enable experimental features (default: false)

Installation Methods

Hosted (recommended)
NPM Package (STDIO)
Local Development

Use your MCP client config:

{
  "mcpServers": {
    "browserbase": {
      "url": "https://mcp.browserbase.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_BROWSERBASE_API_KEY"
      }
    }
  }
}

For custom models, include modelName and modelApiKey:

{
  "mcpServers": {
    "browserbase": {
      "url": "https://mcp.browserbase.com/mcp?modelName=openai/gpt-4.1&modelApiKey=YOUR_MODEL_API_KEY",
      "headers": {
        "Authorization": "Bearer YOUR_BROWSERBASE_API_KEY"
      }
    }
  }
}

The easiest way to get started locally is using our NPM package.

If you would like to use a different model, you have to pass the model name and keys in the args. More info in the Local Command-Line Flags section.

Add to MCP Config

Go into your MCP Config JSON and add the Browserbase Server:

{
  "mcpServers": {
    "browserbase": {
      "command": "npx",
      "args": ["@browserbasehq/mcp"],
      "env": {
        "BROWSERBASE_API_KEY": "your_api_key",
        "GEMINI_API_KEY": "your_gemini_api_key"
      }
    }
  }
}

Restart your MCP client

That’s it! Reload your MCP client and you will be able to use Browserbase.

For local development or customization, you can run the server locally.

Clone and build

# Clone the Repo
git clone https://github.com/browserbase/mcp-server-browserbase.git
cd mcp-server-browserbase

# Install the dependencies and build the project
npm install && npm run build

Choose your transport method

You can run locally using either STDIO or Streamable HTTP.

STDIO
Self-hosted Streamable HTTP

Add the following to your MCP Config JSON file:

{
  "mcpServers": {
    "browserbase": {
      "command": "node",
      "args": ["/path/to/mcp-server-browserbase/cli.js"],
      "env": {
        "BROWSERBASE_API_KEY": "your_api_key",
        "GEMINI_API_KEY": "your_gemini_api_key"
      }
    }
  }
}

First, run the server:

node cli.js --port 8931

Then add this to your MCP Config JSON file:

{
  "mcpServers": {
    "browserbase": {
      "url": "http://localhost:8931/mcp",
      "env": {
        "BROWSERBASE_API_KEY": "your_api_key",
        "GEMINI_API_KEY": "your_gemini_api_key"
      }
    }
  }
}

Restart your client

Reload your MCP client and you should be good to go!

Verify Installation

Restart your MCP client

Restart/refresh your MCP client app and verify tools are available.

Test the integration

Get started using our MCP Server by asking your MCP client to navigate to any page and see your Browserbase Browser in action on the dashboard.

Try: “Navigate to example.com and extract the main heading”

Model Context Protocol (MCP) Docs

Learn more about the MCP protocol

Browserbase Documentation

Explore Browserbase features and capabilities

Support

Get help from our support team

First Steps

The Basics

Configuration

Best Practices

Integrations

Reference

Browserbase MCP Server Setup

Quick Installation

Install with Cursor

Endpoint

Prerequisites

Authentication and Query Parameters (Hosted Streamable HTTP)

Required for tool calls

Authorization

Optional

Available Tools

Local Command-Line Flags

Installation Methods

Verify Installation

Further Reading

Model Context Protocol (MCP) Docs

Browserbase Documentation

Support

​Quick Installation

Install with Cursor

​Endpoint

​Prerequisites

​Authentication and Query Parameters (Hosted Streamable HTTP)

​Required for tool calls

Authorization

​Optional

​Available Tools

​Local Command-Line Flags

​Installation Methods

​Verify Installation

​Further Reading

Model Context Protocol (MCP) Docs

Browserbase Documentation

Support

Quick Installation

Endpoint

Prerequisites

Authentication and Query Parameters (Hosted Streamable HTTP)

Required for tool calls

Optional

Available Tools

Local Command-Line Flags

Installation Methods

Verify Installation

Further Reading