Browserbase MCP Server Setup

Add the Browserbase MCP Server to your MCP client

Quick Installation

Install with Cursor

One-click installation directly in Cursor

You can also add Browserbase MCP to Claude Code with a single command:

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

1. Get your Browserbase credentials

   Get your Browserbase API key from the Browserbase Dashboard.

   

   Then copy your API Key directly from the input.

Query Parameters (Hosted Streamable HTTP)

Required for tool calls

browserbaseApiKey

Browserbase API key.

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"
advancedStealth	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-server-browserbase with flags or local development setup).

Flag	Description
--proxies	Enable Browserbase proxies for the session
--advancedStealth	Enable Browserbase Advanced Stealth (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)

Use your MCP client config:

{
  "mcpServers": {
    "browserbase": {
      "url": "https://mcp.browserbase.com/mcp?browserbaseApiKey=YOUR_BROWSERBASE_API_KEY"
    }
  }
}

For custom models, include modelName and modelApiKey:

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

NPM Package (STDIO)

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 here.

1. Add to MCP Config

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

   Claude Desktop

   {
     "mcpServers": {
       "browserbase": {
         "command": "npx",
         "args": ["@browserbasehq/mcp-server-browserbase"],
         "env": {
           "BROWSERBASE_API_KEY": "your_api_key",
           "GEMINI_API_KEY": "your_gemini_api_key"
         }
       }
     }
   }
   
2. Restart your MCP client

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

Local Development

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

1. 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
   
2. Choose your transport method

   You can run locally using either STDIO or Streamable HTTP.

   STDIO

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

   Self-hosted Streamable HTTP

   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"
         }
       }
     }
   }
   
3. Restart your client

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

Verify Installation

1. Restart your MCP client

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

2. 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”

Further Reading

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