### Direct Installation Setup for Self-Hosted MCP Server

Source: https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md

Steps to clone the repository, install dependencies, and build the self-hosted Browserbase MCP server for local execution.

```bash
git clone https://github.com/browserbase/mcp-server-browserbase.git
cd mcp-server-browserbase
npm install && npm run build
```

--------------------------------

### Configure Direct Installation for Self-Hosted MCP Server

Source: https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md

Configure your MCP client to use the self-hosted Browserbase MCP server installed directly from the repository. Environment variables are required.

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

--------------------------------

### Browser Automation Workflow Example

Source: https://context7.com/browserbase/mcp-server-browserbase/llms.txt

Demonstrates a complete browser automation workflow using MCP client calls, including session management, navigation, interaction, observation, and data extraction.

```typescript
// Step 1: Start a browser session
const startResult = await mcpClient.callTool("start", {});
// Returns: { "success": true, "data": { "sessionId": "bb_sess_xyz789" } }
```

```typescript
// Step 2: Navigate to target website
const navResult = await mcpClient.callTool("navigate", {
  url: "https://news.ycombinator.com"
});
// Returns: { "success": true, "data": { "url": "https://news.ycombinator.com" } }
```

```typescript
// Step 3: Observe available actions on the page
const observeResult = await mcpClient.callTool("observe", {
  instruction: "Find all news article links on the front page"
});
// Returns: Array of clickable article elements
```

```typescript
// Step 4: Extract structured data
const extractResult = await mcpClient.callTool("extract", {
  instruction: "Extract the top 10 article titles with their scores and comment counts"
});
// Returns: { "success": true, "data": { "articles": [...] } }
```

```typescript
// Step 5: Perform an action
const actResult = await mcpClient.callTool("act", {
  action: "Click on the first article link"
});
// Returns: { "success": true, "data": { "success": true } }
```

```typescript
// Step 6: Extract content from the article page
const articleContent = await mcpClient.callTool("extract", {
  instruction: "Extract the article title and full text content"
});
```

```typescript
// Step 7: End the session when done
const endResult = await mcpClient.callTool("end", {});
// Returns: { "success": true }
```

--------------------------------

### MCP Tool: Start Browser Session

Source: https://context7.com/browserbase/mcp-server-browserbase/llms.txt

Call the 'start' tool to create or reuse a Browserbase browser session. This must be called before other browser automation tools. It returns a session ID for debugging.

```typescript
// MCP Tool Call
{
  "name": "start",
  "arguments": {}
}

// Response
{
  "success": true,
  "data": {
    "sessionId": "bb_sess_abc123def456"
  }
}

// The session is now accessible at:
// https://www.browserbase.com/sessions/bb_sess_abc123def456
```

--------------------------------

### MCP Configuration - Hosted SHTTP

Source: https://context7.com/browserbase/mcp-server-browserbase/llms.txt

Configure your MCP client to use the Browserbase hosted server for the easiest setup with built-in Gemini LLM costs included.

```APIDOC
## MCP Configuration - Hosted SHTTP

Configure your MCP client to use the Browserbase hosted server for the easiest setup with built-in Gemini LLM costs included.

```json
{
  "mcpServers": {
    "browserbase": {
      "type": "http",
      "url": "https://mcp.browserbase.com/mcp"
    }
  }
}
```

For clients without SHTTP support, use the mcp-remote proxy:

```json
{
  "mcpServers": {
    "browserbase": {
      "command": "npx",
      "args": ["mcp-remote", "https://mcp.browserbase.com/mcp"]
    }
  }
}
```
```

--------------------------------

### Tool: start

Source: https://context7.com/browserbase/mcp-server-browserbase/llms.txt

Creates or reuses a Browserbase browser session. This tool must be called before any other browser automation tools. It initializes a Stagehand instance connected to a cloud browser and returns the session ID for debugging via the Browserbase Live Debugger.

```APIDOC
## Tool: start

Creates or reuses a Browserbase browser session. This tool must be called before any other browser automation tools. It initializes a Stagehand instance connected to a cloud browser and returns the session ID for debugging via the Browserbase Live Debugger.

### Request Example
```typescript
// MCP Tool Call
{
  "name": "start",
  "arguments": {}
}
```

### Response Example
```typescript
// Response
{
  "success": true,
  "data": {
    "sessionId": "bb_sess_abc123def456"
  }
}

// The session is now accessible at:
// https://www.browserbase.com/sessions/bb_sess_abc123def456
```
```

--------------------------------

### Create Server Instance Programmatically

Source: https://context7.com/browserbase/mcp-server-browserbase/llms.txt

Initialize the MCP server programmatically for Node.js applications. This example shows creating a server with custom configuration, including API keys, proxy settings, and viewport dimensions, and connecting via STDIO transport.

```typescript
import createServer from "@browserbasehq/mcp";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

// Create server with configuration
const server = createServer({
  config: {
    browserbaseApiKey: "bb_live_your_api_key_here",
    browserbaseProjectId: "your_project_id_here",
    proxies: true,
    advancedStealth: false,
    keepAlive: true,
    context: {
      contextId: "optional_context_id",
      persist: true
    },
    viewPort: {
      browserWidth: 1920,
      browserHeight: 1080
    },
    modelName: "google/gemini-2.5-flash-lite",
    modelApiKey: "your_gemini_api_key",
    experimental: false
  }
});

// Connect via STDIO transport
const transport = new StdioServerTransport();
await server.connect(transport);
```

--------------------------------

### Start MCP Server with HTTP Transport

Source: https://context7.com/browserbase/mcp-server-browserbase/llms.txt

Launches the MCP server using HTTP transport for remote access and multi-client support. Ensure environment variables for API and project IDs are set.

```typescript
import createServer from "@browserbasehq/mcp";
import { ServerList } from "@browserbasehq/mcp/server";
import { startHttpTransport } from "@browserbasehq/mcp/transport";

const config = {
  browserbaseApiKey: process.env.BROWSERBASE_API_KEY,
  browserbaseProjectId: process.env.BROWSERBASE_PROJECT_ID,
  server: {
    port: 3000,
    host: "localhost"  // Use "0.0.0.0" for external access
  }
};

const serverList = new ServerList(async () =>
  createServer({ config })
);

// Start HTTP server on port 3000
startHttpTransport(3000, "localhost", serverList);

// Server is now accessible at http://localhost:3000/mcp
// Client config:
// {
//   "mcpServers": {
//     "browserbase": {
//       "type": "http",
//       "url": "http://localhost:3000/mcp"
//     }
//   }
// }
```

--------------------------------

### Extract Specific Data Tool Call

Source: https://context7.com/browserbase/mcp-server-browserbase/llms.txt

Use the extract tool with an instruction to retrieve specific data from the page. This example shows extracting product names and prices.

```typescript
// MCP Tool Call - Extract specific data
{
  "name": "extract",
  "arguments": {
    "instruction": "Extract all product names and prices from the listing"
  }
}

// Response
{
  "success": true,
  "data": {
    "products": [
      { "name": "Wireless Mouse", "price": "$29.99" },
      { "name": "Mechanical Keyboard", "price": "$89.99" },
      { "name": "USB-C Hub", "price": "$45.00" }
    ]
  }
}
```

--------------------------------

### Configure NPM-based Self-Hosted MCP Server

Source: https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md

Configure your MCP client to use the self-hosted Browserbase MCP server installed via NPM. Ensure environment variables for API keys are set.

```json
{
  "mcpServers": {
    "browserbase": {
      "command": "npx",
      "args": ["@browserbasehq/mcp"],
      "env": {
        "BROWSERBASE_API_KEY": "",
        "BROWSERBASE_PROJECT_ID": "",
        "GEMINI_API_KEY": ""
      }
    }
  }
}
```

--------------------------------

### Act Tool - Click Button

Source: https://context7.com/browserbase/mcp-server-browserbase/llms.txt

Use the act tool to perform natural language actions on the current page. This example shows how to click a button. The action string is interpreted by Stagehand's AI.

```typescript
// MCP Tool Call - Click a button
{
  "name": "act",
  "arguments": {
    "action": "Click the 'Sign In' button"
  }
}

// Response
{
  "success": true,
  "data": {
    "success": true,
    "message": "Action completed",
    "action": "Click the 'Sign In' button"
  }
}
```

--------------------------------

### Act Tool - Fill Form

Source: https://context7.com/browserbase/mcp-server-browserbase/llms.txt

Use the act tool to interact with form elements. This example demonstrates typing text into an email input field.

```typescript
// MCP Tool Call - Fill a form
{
  "name": "act",
  "arguments": {
    "action": "Type 'user@example.com' into the email input field"
  }
}
```

--------------------------------

### Extract General Content Tool Call

Source: https://context7.com/browserbase/mcp-server-browserbase/llms.txt

Call the extract tool without an instruction to get general page content. This is useful for a broad overview of the page's text and structure.

```typescript
// MCP Tool Call - Extract without instruction (general extraction)
{
  "name": "extract",
  "arguments": {}
}

// Response
{
  "success": true,
  "data": {
    "title": "Product Catalog - TechStore",
    "content": "Browse our selection of computer accessories..."
  }
}
```

--------------------------------

### Configure Self-Hosted MCP Server with NPM

Source: https://context7.com/browserbase/mcp-server-browserbase/llms.txt

Run the MCP server locally using npm. Requires Browserbase credentials and an API key for your chosen AI model provider.

```json
{
  "mcpServers": {
    "browserbase": {
      "command": "npx",
      "args": ["@browserbasehq/mcp"],
      "env": {
        "BROWSERBASE_API_KEY": "bb_live_your_api_key_here",
        "BROWSERBASE_PROJECT_ID": "your_project_id_here",
        "GEMINI_API_KEY": "your_gemini_api_key_here"
      }
    }
  }
}
```

--------------------------------

### MCP Configuration - Advanced Options

Source: https://context7.com/browserbase/mcp-server-browserbase/llms.txt

Enable proxies, stealth mode, custom viewport, and persistent context for advanced browser automation scenarios.

```APIDOC
## MCP Configuration - Advanced Options

Enable proxies, stealth mode, custom viewport, and persistent context for advanced browser automation scenarios.

```json
{
  "mcpServers": {
    "browserbase": {
      "command": "npx",
      "args": [
        "@browserbasehq/mcp",
        "--proxies",
        "--advancedStealth",
        "--keepAlive",
        "--browserWidth", "1920",
        "--browserHeight", "1080",
        "--contextId", "your_context_id_here",
        "--persist", "true",
        "--experimental"
      ],
      "env": {
        "BROWSERBASE_API_KEY": "bb_live_your_api_key_here",
        "BROWSERBASE_PROJECT_ID": "your_project_id_here",
        "GEMINI_API_KEY": "your_gemini_api_key_here"
      }
    }
  }
}
```
```

--------------------------------

### Configure Advanced MCP Server Options

Source: https://context7.com/browserbase/mcp-server-browserbase/llms.txt

Enable advanced options for the MCP server, including proxies, stealth mode, custom viewport dimensions, and persistent context.

```json
{
  "mcpServers": {
    "browserbase": {
      "command": "npx",
      "args": [
        "@browserbasehq/mcp",
        "--proxies",
        "--advancedStealth",
        "--keepAlive",
        "--browserWidth", "1920",
        "--browserHeight", "1080",
        "--contextId", "your_context_id_here",
        "--persist", "true",
        "--experimental"
      ],
      "env": {
        "BROWSERBASE_API_KEY": "bb_live_your_api_key_here",
        "BROWSERBASE_PROJECT_ID": "your_project_id_here",
        "GEMINI_API_KEY": "your_gemini_api_key_here"
      }
    }
  }
}
```

--------------------------------

### MCP Configuration - Self-Hosted NPM

Source: https://context7.com/browserbase/mcp-server-browserbase/llms.txt

Run the MCP server locally via npm with your own API keys. Requires Browserbase credentials and a Gemini API key (or custom model provider).

```APIDOC
## MCP Configuration - Self-Hosted NPM

Run the MCP server locally via npm with your own API keys. Requires Browserbase credentials and a Gemini API key (or custom model provider).

```json
{
  "mcpServers": {
    "browserbase": {
      "command": "npx",
      "args": ["@browserbasehq/mcp"],
      "env": {
        "BROWSERBASE_API_KEY": "bb_live_your_api_key_here",
        "BROWSERBASE_PROJECT_ID": "your_project_id_here",
        "GEMINI_API_KEY": "your_gemini_api_key_here"
      }
    }
  }
}
```
```

--------------------------------

### Docker Build for Self-Hosted MCP Server

Source: https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md

Command to build a Docker image for the self-hosted Browserbase MCP server.

```bash
git clone https://github.com/browserbase/mcp-server-browserbase.git
cd mcp-server-browserbase
docker build -t mcp-browserbase .
```

--------------------------------

### MCP Configuration - Custom Model Provider

Source: https://context7.com/browserbase/mcp-server-browserbase/llms.txt

Configure a custom AI model provider (Claude, GPT-4o, etc.) instead of the default Gemini. Requires the model's API key.

```APIDOC
## MCP Configuration - Custom Model Provider

Configure a custom AI model provider (Claude, GPT-4o, etc.) instead of the default Gemini. Requires the model's API key.

```json
{
  "mcpServers": {
    "browserbase": {
      "command": "npx",
      "args": [
        "@browserbasehq/mcp",
        "--modelName", "anthropic/claude-sonnet-4.5",
        "--modelApiKey", "sk-ant-your_anthropic_api_key_here"
      ],
      "env": {
        "BROWSERBASE_API_KEY": "bb_live_your_api_key_here",
        "BROWSERBASE_PROJECT_ID": "your_project_id_here"
      }
    }
  }
}
```
```

--------------------------------

### Run MCP Server via CLI

Source: https://context7.com/browserbase/mcp-server-browserbase/llms.txt

Execute the MCP server from the command line with various configuration options. Environment variables are often used for authentication.

```bash
# Basic usage with environment variables
export BROWSERBASE_API_KEY="bb_live_your_api_key"
export BROWSERBASE_PROJECT_ID="your_project_id"
export GEMINI_API_KEY="your_gemini_key"
npx @browserbasehq/mcp
```

```bash
# With custom model (Claude)
npx @browserbasehq/mcp \
  --modelName "anthropic/claude-sonnet-4.5" \
  --modelApiKey "sk-ant-your_key"
```

```bash
# With HTTP transport for remote access
npx @browserbasehq/mcp --port 3000 --host 0.0.0.0
```

```bash
# With all advanced options
npx @browserbasehq/mcp \
  --browserbaseApiKey "bb_live_key" \
  --browserbaseProjectId "project_id" \
  --proxies \
  --advancedStealth \
  --keepAlive \
  --browserWidth 1920 \
  --browserHeight 1080 \
  --contextId "context_123" \
  --persist true \
  --experimental
```

```bash
# Local development from cloned repo
git clone https://github.com/browserbase/mcp-server-browserbase.git
cd mcp-server-browserbase
npm install && npm run build
node cli.js
```

--------------------------------

### Configure Docker for Self-Hosted MCP Server

Source: https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md

Configure your MCP client to use the self-hosted Browserbase MCP server running in a Docker container. Environment variables are passed via the run command.

```json
{
  "mcpServers": {
    "browserbase": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "BROWSERBASE_API_KEY",
        "-e",
        "BROWSERBASE_PROJECT_ID",
        "-e",
        "GEMINI_API_KEY",
        "mcp-browserbase"
      ],
      "env": {
        "BROWSERBASE_API_KEY": "",
        "BROWSERBASE_PROJECT_ID": "",
        "GEMINI_API_KEY": ""
      }
    }
  }
}
```

--------------------------------

### Configure Custom Model Provider for MCP Server

Source: https://context7.com/browserbase/mcp-server-browserbase/llms.txt

Configure the MCP server to use a custom AI model provider like Claude or GPT-4o instead of the default Gemini. Requires the model's API key.

```json
{
  "mcpServers": {
    "browserbase": {
      "command": "npx",
      "args": [
        "@browserbasehq/mcp",
        "--modelName", "anthropic/claude-sonnet-4.5",
        "--modelApiKey", "sk-ant-your_anthropic_api_key_here"
      ],
      "env": {
        "BROWSERBASE_API_KEY": "bb_live_your_api_key_here",
        "BROWSERBASE_PROJECT_ID": "your_project_id_here"
      }
    }
  }
}
```

--------------------------------

### Configure Self-Hosted MCP Server with Docker

Source: https://context7.com/browserbase/mcp-server-browserbase/llms.txt

Configure the MCP client to use a self-hosted MCP server deployed via Docker. Ensure environment variables for API keys are set.

```json
{
  "mcpServers": {
    "browserbase": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "BROWSERBASE_API_KEY",
        "-e", "BROWSERBASE_PROJECT_ID",
        "-e", "GEMINI_API_KEY",
        "mcp-browserbase"
      ],
      "env": {
        "BROWSERBASE_API_KEY": "bb_live_your_api_key_here",
        "BROWSERBASE_PROJECT_ID": "your_project_id_here",
        "GEMINI_API_KEY": "your_gemini_api_key_here"
      }
    }
  }
}
```

--------------------------------

### MCP Configuration - Self-Hosted Docker

Source: https://context7.com/browserbase/mcp-server-browserbase/llms.txt

Deploy via Docker container for isolated execution environments.

```APIDOC
## MCP Configuration - Self-Hosted Docker

Deploy via Docker container for isolated execution environments.

```bash
# Build the Docker image
git clone https://github.com/browserbase/mcp-server-browserbase.git
cd mcp-server-browserbase
docker build -t mcp-browserbase .
```

```json
{
  "mcpServers": {
    "browserbase": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "BROWSERBASE_API_KEY",
        "-e", "BROWSERBASE_PROJECT_ID",
        "-e", "GEMINI_API_KEY",
        "mcp-browserbase"
      ],
      "env": {
        "BROWSERBASE_API_KEY": "bb_live_your_api_key_here",
        "BROWSERBASE_PROJECT_ID": "your_project_id_here",
        "GEMINI_API_KEY": "your_gemini_api_key_here"
      }
    }
  }
}
```
```

--------------------------------

### Observe Tool Call

Source: https://context7.com/browserbase/mcp-server-browserbase/llms.txt

Use the observe tool to find actionable elements on the page based on an instruction. This helps in understanding possible interactions before performing them. The response includes element details, selectors, and actions.

```typescript
// MCP Tool Call
{
  "name": "observe",
  "arguments": {
    "instruction": "Find all clickable buttons and links in the navigation"
  }
}

// Response
{
  "success": true,
  "data": [
    {
      "element": "button",
      "description": "Sign In button",
      "selector": "#signin-btn",
      "action": "click"
    },
    {
      "element": "link",
      "description": "Home navigation link",
      "selector": "nav a[href='/']",
      "action": "click"
    },
    {
      "element": "link",
      "description": "Products dropdown menu",
      "selector": "nav a[href='/products']",
      "action": "click"
    }
  ]
}
```

--------------------------------

### Configure Fallback Transport for Hosted MCP Server

Source: https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md

Use this JSON configuration if your client does not support SHTTP, falling back to a command-based execution for the hosted Browserbase MCP server.

```json
{
  "mcpServers": {
    "browserbase": {
      "command": "npx",
      "args": ["mcp-remote", "https://mcp.browserbase.com/mcp"]
    }
  }
}
```

--------------------------------

### Navigate Browser Tool Call

Source: https://context7.com/browserbase/mcp-server-browserbase/llms.txt

Use the navigate tool to load a specified URL and wait for DOM content to load. This is useful for preparing the browser for subsequent actions or data extraction.

```typescript
// MCP Tool Call
{
  "name": "navigate",
  "arguments": {
    "url": "https://www.example.com/login"
  }
}

// Response
{
  "success": true,
  "data": {
    "url": "https://www.example.com/login"
  }
}
```

--------------------------------

### Configure SHTTP Transport for Hosted MCP Server

Source: https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md

Use this JSON configuration if your client supports SHTTP to connect to the hosted Browserbase MCP server.

```json
{
  "mcpServers": {
    "browserbase": {
      "type": "http",
      "url": "https://mcp.browserbase.com/mcp"
    }
  }
}
```

--------------------------------

### Configure Custom LLM Model in MCP Server

Source: https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md

Use this JSON configuration to set up the Browserbase MCP server to use a custom LLM model, such as Anthropic's Claude. Ensure you provide the correct API key for your chosen model provider.

```json
{
  "mcpServers": {
    "browserbase": {
      "command": "npx",
      "args": [
        "@browserbasehq/mcp",
        "--modelName",
        "anthropic/claude-sonnet-4.5",
        "--modelApiKey",
        "your-anthropic-api-key"
      ],
      "env": {
        "BROWSERBASE_API_KEY": "",
        "BROWSERBASE_PROJECT_ID": ""
      }
    }
  }
}
```

--------------------------------

### Tool: end

Source: https://context7.com/browserbase/mcp-server-browserbase/llms.txt

Closes the current Browserbase browser session and cleans up resources. Call this tool when browser automation tasks are complete to free up session resources.

```APIDOC
## Tool: end

Closes the current Browserbase browser session and cleans up resources. Call this tool when browser automation tasks are complete to free up session resources.

### Request Example
```typescript
// MCP Tool Call
{
  "name": "end",
  "arguments": {}
}
```

### Response Example
```typescript
// Response
{
  "success": true
}
```
```

--------------------------------

### Act Tool - Complex Interaction

Source: https://context7.com/browserbase/mcp-server-browserbase/llms.txt

The act tool can handle complex interactions, such as scrolling and then clicking an element. Provide a detailed natural language instruction.

```typescript
// MCP Tool Call - Complex interaction
{
  "name": "act",
  "arguments": {
    "action": "Scroll down and click the 'Load More' button"
  }
}
```

--------------------------------

### Extract Structured Information Tool Call

Source: https://context7.com/browserbase/mcp-server-browserbase/llms.txt

Use the extract tool with a detailed instruction to extract specific structured information, such as an article's title, author, date, and content.

```typescript
// MCP Tool Call - Extract structured information
{
  "name": "extract",
  "arguments": {
    "instruction": "Extract the article title, author, publication date, and main content"
  }
}
```

--------------------------------

### MCP Tool: End Browser Session

Source: https://context7.com/browserbase/mcp-server-browserbase/llms.txt

Call the 'end' tool to close the current Browserbase browser session and clean up resources. Use this when browser automation tasks are complete.

```typescript
// MCP Tool Call
{
  "name": "end",
  "arguments": {}
}

// Response
{
  "success": true
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.