Browserbase MCP Server Configuration

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

Flag	Description
`--proxies`	Enable Browserbase proxies for the session
`--advancedStealth`	Enable 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

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.

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

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

# Start server
node cli.js --port 8931

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

Advanced Features

Proxies
Advanced Stealth
Contexts

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

Enable advanced anti-detection features for enhanced stealth browsing.

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

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

Browser Customization

Viewport Sizing
Cookie Injection

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)

Inject session cookies for authentication. Useful when persistent contexts don’t handle session cookies.

{
  "mcpServers": {
    "browserbase": {
      "command": "npx",
      "args": [
        "@browserbasehq/mcp",
        "--cookies",
        "[{\"name\": \"session\", \"value\": \"abc123\", \"domain\": \".example.com\", \"path\": \"/\", \"httpOnly\": true, \"secure\": true}]"
      ],
      "env": {
        "BROWSERBASE_API_KEY": "your_api_key",
        "BROWSERBASE_PROJECT_ID": "your_project_id",
        "GEMINI_API_KEY": "your_gemini_api_key"
      }
    }
  }
}

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

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

{
  "mcpServers": {
    "browserbase": {
      "command": "npx",
      "args": [
        "@browserbasehq/mcp",
        "--modelName", "anthropic/claude-3-5-sonnet-latest",
        "--modelApiKey", "your_anthropic_api_key"
      ],
      "env": {
        "BROWSERBASE_API_KEY": "your_api_key",
        "BROWSERBASE_PROJECT_ID": "your_project_id"
      }
    }
  }
}

Development Configuration

Debug Mode
Custom Host/Port

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

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

Browserbase Documentation

Complete platform documentation

Stagehand Docs

AI-powered browser automation

Support

Get help from our team

Get Started

Concepts

Playbooks

Reference

Integrations

Browserbase MCP Server Configuration

Configuration Overview

Environment Variables

BROWSERBASE_API_KEY

BROWSERBASE_PROJECT_ID

Command-Line Flags

Available Flags

Configuration Examples

Basic Configuration

Advanced Features

Browser Customization

Model Configuration

Development Configuration

Best Practices

Further Reading

Browserbase Documentation

Stagehand Docs

Support

​Configuration Overview

​Environment Variables

BROWSERBASE_API_KEY

BROWSERBASE_PROJECT_ID

​Command-Line Flags

​Available Flags

​Configuration Examples

​Basic Configuration

​Advanced Features

​Browser Customization

​Model Configuration

​Development Configuration

​Best Practices

​Further Reading

Browserbase Documentation

Stagehand Docs

Support

Configuration Overview

Environment Variables

Command-Line Flags

Available Flags

Configuration Examples

Basic Configuration

Advanced Features

Browser Customization

Model Configuration

Development Configuration

Best Practices

Further Reading