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

​
Configuration Examples

​
Basic Configuration

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

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",
        "BROWSERBASE_PROJECT_ID": "your_project_id",
        "GEMINI_API_KEY": "your_gemini_api_key"
      }
    }
  }
}

​
Browser Customization

Customize browser window dimensions. Default is 1024x768. Recommended aspect ratios: 16:9.
{
  "mcpServers": {
    "browserbase": {
      "command": "npx",
      "args": [
        "@browserbasehq/mcp",
        "--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.
Google Gemini (Default)
  • google/gemini-2.0-flash (default)
  • google/gemini-1.5-pro
  • google/gemini-1.5-flash
OpenAI
  • openai/gpt-4o
  • openai/gpt-4o-mini
  • openai/o1-mini
  • openai/o1-preview
  • openai/o3-mini
Anthropic Claude
  • anthropic/claude-3-5-sonnet-latest
  • anthropic/claude-3-7-sonnet-latest
View full list of supported models

​
Development Configuration

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

​
Best Practices

​
Further Reading

Browserbase Documentation

Complete platform documentation

Stagehand Docs

AI-powered browser automation

Support

Get help from our team