Skip to main content

Overview

The Browserbase MCP Server brings powerful browser automation capabilities to AI assistants through the Model Context Protocol (MCP). Built on Stagehand, this integration provides AI-powered web automation using natural language commands.
This server enables AI assistants like Claude to control browsers, navigate websites, interact with web elements, and extract data—all through simple conversational commands.

Key Features

Natural Language Automation

Control browsers using plain English commands like “click the login button” or “fill out the contact form”

Web Interaction

Navigate, click, and fill forms with ease

Data Extraction

Extract structured data from any website automatically

Screenshot Capture

Capture and analyze webpage screenshots programmatically

Installation Methods

Choose the installation method that best fits your needs: Go to smithery.ai and enter your API keys to get a remote hosted URL:
{
  "mcpServers": {
    "browserbase": {
      "url": "your-smithery-url.com"
    }
  }
}
When using the remote server, Gemini LLM costs are included.

NPM Package (STDIO)

The easiest way to get started locally:
{
  "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"
      }
    }
  }
}

Local Development

For customization or local testing:
# Clone and build
git clone https://github.com/browserbase/mcp-server-browserbase.git
cd mcp-server-browserbase
npm install && npm run build

# Run with STDIO
node cli.js

# Or run with SHTTP
node cli.js --port 8931

Quick Start

Prerequisites

  1. Get your Browserbase API key and project ID from the Browserbase Dashboard
  2. Get your LLM provider API key (Gemini, OpenAI, or Claude)

Basic Setup

  1. Add the server to your MCP client configuration (see installation methods above)
  2. Restart your MCP client
  3. Verify the tools are available (look for the 🔨 icon)

Test the Integration

Try asking your AI assistant:
"Navigate to google.com and take a screenshot"

Using MCP Servers with Stagehand

You can connect external MCP servers to your Stagehand agents for enhanced capabilities:

Connect to an MCP Server

import { connectToMCPServer, Stagehand } from "@browserbasehq/stagehand";

// Method 1: Connect via URL
const mcpClient = await connectToMCPServer(
  "https://mcp.example.com/server?apiKey=your_key"
);

// Method 2: Connect via stdio
const mcpClient = await connectToMCPServer({
  command: "npx",
  args: ["-y", "@example/mcp-server"],
  env: {
    API_KEY: process.env.EXAMPLE_API_KEY
  }
});

Use with Stagehand Agent

const stagehand = new Stagehand({
  env: "BROWSERBASE",
  model: "openai/gpt-4o",
});

await stagehand.init();

const page = stagehand.context.pages()[0];
await page.goto("https://www.google.com");

// Create agent with MCP integration
const agent = stagehand.agent({
  integrations: [mcpClient],
  systemPrompt: `You are a helpful assistant with access to external tools.
    Use the available tools to enhance your capabilities.`
});

const result = await agent.execute(
  "Search for the latest AI news and summarize the top results"
);

Example: Exa Search Integration

import { Stagehand } from "@browserbasehq/stagehand";

const stagehand = new Stagehand({
  env: "LOCAL",
  model: "openai/gpt-4o",
  verbose: 1,
});

await stagehand.init();

const page = stagehand.context.pages()[0];
await page.goto("https://www.google.com");

const agent = stagehand.agent({
  integrations: [
    `https://mcp.exa.ai/mcp?exaApiKey=${process.env.EXA_API_KEY}`,
  ],
  systemPrompt: `You are a helpful assistant that can use a browser and external tools.
    You have access to the Exa search tool to find information on the web.
    When looking for products to buy, search for current and reliable information.`
});

const result = await agent.execute(
  "Use Exa to search for the top headphones of 2025. Then go through the checkout flow for the best one."
);

console.log(result);
await stagehand.close();

Example: Supabase Integration

import { connectToMCPServer, Stagehand } from "@browserbasehq/stagehand";

const stagehand = new Stagehand({
  env: "LOCAL",
  verbose: 1,
});

await stagehand.init();

const page = stagehand.context.pages()[0];
await page.goto("https://www.opentable.com/");

// Connect to Supabase MCP server
const supabaseClient = await connectToMCPServer(
  `https://server.smithery.ai/@supabase-community/supabase-mcp/mcp?api_key=${process.env.SMITHERY_API_KEY}`
);

const agent = stagehand.agent({
  model: "openai/computer-use-preview",
  integrations: [supabaseClient],
});

const result = await agent.execute(
  "Search for restaurants in New Brunswick, NJ. Then use Supabase to insert the name of the first result into a table called 'restaurants'."
);

console.log(result);
await stagehand.close();

Configuration Options

Command-Line Flags

FlagDescription
--proxiesEnable Browserbase proxies
--advancedStealthEnable Advanced Stealth mode (Scale Plan)
--keepAliveKeep browser session alive
--contextId <id>Use specific Browserbase context
--persist [boolean]Persist context (default: true)
--port <port>Port for SHTTP transport
--host <host>Host to bind server (default: localhost)
--browserWidth <width>Viewport width (default: 1024)
--browserHeight <height>Viewport height (default: 768)
--modelName <model>AI model to use (default: gemini-2.0-flash)
--modelApiKey <key>API key for custom model
--experimentalEnable experimental features

Advanced Configuration Example

{
  "mcpServers": {
    "browserbase": {
      "command": "npx",
      "args": [
        "@browserbasehq/mcp-server-browserbase",
        "--proxies",
        "--browserWidth", "1920",
        "--browserHeight", "1080",
        "--modelName", "gpt-4o",
        "--modelApiKey", "your_openai_key"
      ],
      "env": {
        "BROWSERBASE_API_KEY": "your_api_key",
        "BROWSERBASE_PROJECT_ID": "your_project_id"
      }
    }
  }
}

Available Models

Google Gemini (Default):
  • gemini-2.0-flash (default)
  • gemini-2.5-pro
  • gemini-2.5-flash
OpenAI:
  • gpt-4o
  • gpt-4o-mini
  • gpt-4-turbo
Anthropic Claude:
  • claude-sonnet-4-5
  • claude-haiku-4-5

Use Cases

  • Track product prices and availability
  • Monitor competitor information
  • Aggregate content from multiple sources
  • Extract contact information and business data

Best Practices

Performance

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

Security

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

Development

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

Resources

MCP Protocol Docs

Learn about Model Context Protocol

Browserbase Docs

Explore Browserbase features

Stagehand Docs

AI-powered browser automation

MCP Server GitHub

View source code and examples

Agent Reference

Learn about Stagehand’s Agent API

Support

Get help from our team

Build docs developers (and LLMs) love