Skip to main content
Cookies must be in Playwright Cookie format.

​
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-server-browserbase 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

BROWSERBASE_PROJECT_ID

Your Browserbase project ID

​
Command-Line Flags

​
Available Flags

FlagDescription
--proxiesEnable Browserbase proxies for the session
--advancedStealthEnable Browserbase Advanced Stealth (Scale Plan only)
--keepAliveEnable 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)
--cookies [json]JSON array of cookies to inject into the browser
--browserWidth <width>Browser viewport width (default: 1024)
--browserHeight <height>Browser viewport height (default: 768)
--modelName <model>The model to use for Stagehand (default: gemini-2.0-flash)
--modelApiKey <key>API key for the custom model provider (required when using custom models)
--experimentalEnable experimental features (default: false)

​
Configuration Examples

​
Basic Configuration

  • Remote URL (SHTTP)
  • NPM Package
  • Local STDIO
  • Local 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.

​
Advanced Features

  • Proxies
  • Advanced Stealth
  • Contexts
Enable Browserbase proxies for IP rotation and geo-location testing.
{
  "mcpServers": {
    "browserbase": {
      "command": "npx",
      "args": ["@browserbasehq/mcp-server-browserbase", "--proxies"],
      "env": {
        "BROWSERBASE_API_KEY": "your_api_key",
        "BROWSERBASE_PROJECT_ID": "your_project_id",
        "GEMINI_API_KEY": "your_gemini_api_key"
      }
    }
  }
}

​
Browser Customization

  • Viewport Sizing
Customize browser window dimensions. Default is 1024x768. Recommended aspect ratios: 16:9.
{
  "mcpServers": {
    "browserbase": {
      "command": "npx",
      "args": [
        "@browserbasehq/mcp-server-browserbase",
        "--browserWidth", "1920",
        "--browserHeight", "1080"
      ],
      "env": {
        "BROWSERBASE_API_KEY": "your_api_key",
        "BROWSERBASE_PROJECT_ID": "your_project_id",
        "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.0 Flash 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
  • Configuration Examples
Google Gemini (Default)
  • google/gemini-2.0-flash (default)
  • google/gemini-1.5-pro
  • google/gemini-1.5-flash
OpenAI
  • openai/gpt-4.1
  • openai/gpt-4o
  • openai/gpt-4o-mini
Anthropic Claude
  • anthropic/claude-sonnet-4-5-20250929
  • anthropic/claude-haiku-4-5-20251001
View full list of supported models

​
Development Configuration

  • Debug Mode
  • Custom Host/Port
Enable detailed logging for troubleshooting and development.
{
  "mcpServers": {
    "browserbase": {
      "command": "npx",
      "args": ["@browserbasehq/mcp-server-browserbase"],
      "env": {
        "BROWSERBASE_API_KEY": "your_api_key",
        "BROWSERBASE_PROJECT_ID": "your_project_id",
        "GEMINI_API_KEY": "your_gemini_api_key",
        "DEBUG": "true"
      }
    }
  }
}

​
Best Practices

  • 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
  • Store API keys securely in environment variables
  • Use Advanced Stealth for sensitive operations
  • Implement proper session management
  • Rotate cookies and contexts regularly
  • 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