Browserbase MCP Server Configuration

Configure your browser automation with command-line flags, environment variables, and advanced options

Configuration Overview

The Browserbase MCP server supports extensive configuration options through command-line flags and environment variables. Configure browser behavior, proxy settings, stealth modes, model selection, and more to customize your browser automation workflows.

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

Environment Variables

Configure the essential Browserbase credentials and optional debugging settings:

BROWSERBASE_API_KEY

Your Browserbase API key for authentication

Command-Line Flags

Available Flags

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/SHTTP 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)

Configuration Examples

Basic Configuration

Remote URL (SHTTP)

Direct SHTTP

{
  "mcpServers": {
    "browserbase": {
      "url": "your-smithery-url.com"
    }
  }
}

When using our remote hosted server, we provide the LLM costs for Gemini, the best performing model in Stagehand.

NPM Package

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

Local STDIO

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

Local SHTTP

# Start server
node cli.js --port 8931

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

Advanced Features

Proxies

Enable Browserbase proxies for IP rotation and geo-location testing.

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

Advanced Stealth

Enable advanced anti-detection features for enhanced stealth browsing.

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

Contexts

Use persistent browser contexts to maintain authentication and state across sessions.

{
  "mcpServers": {
    "browserbase": {
      "command": "npx",
      "args": ["@browserbasehq/mcp", "--contextId", "your_context_id"],
      "env": {
        "BROWSERBASE_API_KEY": "your_api_key"
      }
    }
  }
}

Browser Customization

Viewport Sizing

Customize browser window dimensions. Default is 1288x711. Recommended aspect ratios: 16:9.

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

Common Resolutions:

• Desktop: 1920x1080, 1280x720, 1024x768
• Mobile: 375x667 (iPhone), 360x640 (Android)
• Tablet: 768x1024 (iPad)

Model Configuration

Configure AI models for enhanced browser automation. Stagehand defaults to Google’s Gemini 2.5 Flash Lite but supports multiple providers.

When using any custom model (non-default), you must provide your own API key for that model provider using the --modelApiKey flag.

Available Models

Google Gemini (Default)

• google/gemini-2.5-flash-lite (default)
• google/gemini-2.5-pro
• google/gemini-2.5-flash

OpenAI

• gpt-5-2025-08-07
• gpt-4.1-2025-04-14
• gpt-4o
• gpt-4o-mini

Anthropic Claude

• claude-sonnet-4-5
• claude-haiku-4-5

View full list of supported models

Configuration Examples

OpenAI GPT-4o

{
  "mcpServers": {
    "browserbase": {
      "command": "npx",
      "args": [
        "@browserbasehq/mcp",
        "--modelName", "gpt-4o",
        "--modelApiKey", "your_openai_api_key"
      ],
      "env": {
        "BROWSERBASE_API_KEY": "your_api_key"
      }
    }
  }
}

{
  "mcpServers": {
    "browserbase": {
      "command": "npx",
      "args": [
        "@browserbasehq/mcp",
        "--modelName", "claude-sonnet-4-6",
        "--modelApiKey", "your_anthropic_api_key"
      ],
      "env": {
        "BROWSERBASE_API_KEY": "your_api_key"
      }
    }
  }
}

Development Configuration

Custom Host/Port

Configure custom host and port for SHTTP transport.

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

Best Practices

Performance - How can I optimize browser automation performance?

• Use appropriate viewport sizes for your use case
• Enable proxies only when needed for geo-location
• Choose efficient models (Gemini Flash for speed, GPT-4o for accuracy)
• Reuse contexts for authentication persistence

Security - What security measures should I implement?

• Store API keys securely in environment variables
• Use Advanced Stealth for sensitive operations
• Implement proper session management
• Rotate cookies and contexts regularly

Development - What are the recommended development practices?

• Enable debug mode during development
• Use context persistence for faster iteration
• Test with different viewport sizes
• Monitor session usage and quotas

Production - How should I configure for production environments?

• Use NPM installation for reliability
• Configure appropriate timeouts
• Implement error handling and retries
• Monitor performance and resource usage

Further Reading

Browserbase Documentation

Complete platform documentation

Stagehand Docs

AI-powered browser automation

Support

Get help from our team