Browserbase MCP Server

To run the server locally using Docker, first build the image from the repository, then configure your MCP client to run the container. Ensure you pass the required environment variables through the docker run command.

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

// MCP Config for Docker
{
  "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": ""
      }
    }
  }
}

To run the self-hosted version using NPM, add the @browserbasehq/mcp package to your MCP configuration. You must provide your BROWSERBASE_API_KEY, BROWSERBASE_PROJECT_ID, and GEMINI_API_KEY in the environment variables.

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

The easiest way to use Browserbase MCP is via the hosted SHTTP server at https://mcp.browserbase.com/mcp. This version includes hosted LLM costs for Gemini.

If your MCP client supports SHTTP, use the http type configuration. If it only supports STDIO, use npx mcp-remote to connect to the hosted URL.

// For clients supporting SHTTP
{
  "mcpServers": {
    "browserbase": {
      "type": "http",
      "url": "https://mcp.browserbase.com/mcp"
    }
  }
}

// For clients only supporting STDIO
{
  "mcpServers": {
    "browserbase": {
      "command": "npx",
      "args": ["mcp-remote", "https://mcp.browserbase.com/mcp"]
    }
  }
}

The Browserbase MCP server implements the MCP sampling capability. This allows the server to initiate requests TO the client to ask for LLM completions. This is primarily used for intelligent browser automation, enabling the server to request AI assistance for analyzing web pages and making decisions during a session.

Note: Sampling support is dependent on the MCP client implementation. Not all clients (e.g., Claude Desktop) currently support this capability.

The self-hosted server defaults to google/gemini-2.5-flash-lite. To use a different model (e.g., Claude or GPT-4o), pass the --modelName flag and provide the corresponding API key using the --modelApiKey flag. The model must be supported by Stagehand.

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

The mcp-eval-basic.config.json file defines the configuration for running evaluations against the Browserbase MCP server. It specifies the server connection details, environment variables, success thresholds, and the specific workflows to be tested.

Top-level Configuration Keys

• passThreshold: A float representing the minimum success rate required for an evaluation to pass (e.g., 0.7).
• timeout: The maximum time in milliseconds allowed for the evaluation (e.g., 180000).
• llmJudge: A boolean indicating whether an LLM should be used to judge the results.
• server: An object defining how to connect to the MCP server.
• workflows: An array of workflow objects defining specific test cases.

The server object in the evaluation configuration defines the transport mechanism and execution environment for the MCP server.

Server Configuration Keys

• transport: The communication method (e.g., stdio).
• command: The executable used to run the server (e.g., node).
• args: An array of command-line arguments passed to the command (e.g., ["./cli.js"]).
• env: An object containing the environment variables required by the server. Required variables include:
  • BROWSERBASE_API_KEY
  • BROWSERBASE_PROJECT_ID
  • GEMINI_API_KEY

"server": {
  "transport": "stdio",
  "command": "node",
  "args": ["./cli.js"],
  "env": {
    "BROWSERBASE_API_KEY": "${BROWSERBASE_API_KEY}",
    "BROWSERBASE_PROJECT_ID": "${BROWSERBASE_PROJECT_ID}",
    "GEMINI_API_KEY": "${GEMINI_API_KEY}"
  }
}

The server uses specific environment variables to resolve configuration if they are not provided via CLI.

Browserbase Configuration

• BROWSERBASE_API_KEY: Your Browserbase API key.
• BROWSERBASE_PROJECT_ID: Your Browserbase Project ID.

Model Configuration

If modelApiKey is not provided via CLI, the server looks for:

• GEMINI_API_KEY
• GOOGLE_API_KEY (as a fallback)

Note: If these are not set, the server will log a warning and use dummy values, which will cause API calls to fail.