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:

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

Browserbase supports both local STDIO and hosted Streamable HTTP (SHTTP). Hosted Streamable HTTP is recommended 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.

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"`
`verified`	boolean string	`"true"` or `"false"`

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

Available tools

Every tool below accepts an optional sessionId parameter. Pass the sessionId returned by start to target or reattach to that specific Browserbase session; if omitted, the tool uses the transport’s current active session. This matters for MCP clients (e.g. ChatGPT) that don’t carry the same Mcp-Session-Id across requests: pass sessionId explicitly on every call to reliably target the right browser session. See Session reattachment below.

navigate

Navigate to any URL in the browser

string

required

The URL to navigate to

string

Optional Browserbase session ID to target or reattach to. Defaults to the current active session.

act

Perform an action on the web page using natural language

string

required

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

string

Optional Browserbase session ID to target or reattach to. Defaults to the current active session.

observe

Observe and find actionable elements on the page.

string

required

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

string

Optional Browserbase session ID to target or reattach to. Defaults to the current active session.

extract

Extract data from the current page.

string

Optional extraction instruction.

string

Optional Browserbase session ID to target or reattach to. Defaults to the current active session.

start

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

string

Optional existing Browserbase session ID to reuse instead of creating a new session.

Output

string

Browserbase session ID.

end

Close a Browserbase session.

string

Optional Browserbase session ID to close. Defaults to the current active session. Closing a session by explicit ID only clears the transport’s active-session state when that ID is the current session.

Session reattachment

The hosted endpoint (mcp.browserbase.com) keeps track of an active Browserbase session per MCP transport (Mcp-Session-Id). Some MCP clients open a new transport on every tool call instead of reusing one, which means the server has no active session to fall back to and calls fail with No active session. To work reliably with these clients, pass the sessionId returned by start on every subsequent tool call. An explicit sessionId always takes priority over the transport’s current session. The hosted endpoint adopts a session as the transport’s active session only after confirming that session still exists, so a stale or incorrect sessionId surfaces an error instead of silently redirecting a later call.

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

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

If you’d like to use a different model, pass the model name and keys in the args. More info here.

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’ll 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 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 the Browserbase support team

Integrations

Quick installation

Install with Cursor

Endpoint

Prerequisites

Query parameters (hosted Streamable HTTP)

Required for tool calls

browserbaseApiKey

Optional

Available tools

Session reattachment

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

​Query parameters (hosted Streamable HTTP)

​Required for tool calls

browserbaseApiKey

​Optional

​Available tools

​Session reattachment

​Local command-line flags

​Installation methods

​Verify installation

​Further reading

Model Context Protocol (MCP) docs

Browserbase Documentation

Support

Quick installation

Endpoint

Prerequisites

Query parameters (hosted Streamable HTTP)

Required for tool calls

Optional

Available tools

Session reattachment

Local command-line flags

Installation methods

Verify installation

Further reading