Skip to main content
Glama

mcp-server-browserbase

Official
by browserbase
Apache 2.0
2,134
1,907

Playwright Browserbase MCP Server

cover

The Model Context Protocol (MCP) is an open protocol that enables seamless integration between LLM applications and external data sources and tools. Whether you’re building an AI-powered IDE, enhancing a chat interface, or creating custom AI workflows, MCP provides a standardized way to connect LLMs with the context they need.

How to setup in MCP json

You can either use our Server hosted on NPM or run it completely locally by cloning this repo.

Go into your MCP Config JSON and add the Browserbase Server:

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

Thats it! Reload your MCP client and Claude will be able to use Browserbase.

To run 100% local:

# Clone the Repo git clone https://github.com/browserbase/mcp-server-browserbase.git # Install the dependencies in the proper directory and build the project cd browserbase npm install && npm run build

Then in your MCP Config JSON run the server. To run locally we can use STDIO or self-host over SSE.

STDIO:

To your MCP Config JSON file add the following:

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

SSE:

Run the following command in your terminal. You can add any flags (see options below) that you see fit to customize your configuration.

node cli.js --port 8931

Then in your MCP Config JSON file put the following:

{ "mcpServers": { "browserbase": { "url": "http://localhost:8931/sse", "env": { "BROWSERBASE_API_KEY": "", "BROWSERBASE_PROJECT_ID": "" } } } }

Then reload your MCP client and you should be good to go!

Flags Explained:

The Browserbase MCP server accepts the following command-line flags:

FlagDescription
--browserbaseApiKey <key>Your Browserbase API key for authentication
--browserbaseProjectId <id>Your Browserbase project ID
--proxiesEnable Browserbase proxies for the session
--advancedStealthEnable Browserbase Advanced Stealth (Only for Scale Plan Users)
--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/SSE 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)

These flags can be passed directly to the CLI or configured in your MCP configuration file.

NOTE:

Currently, these flags can only be used with the local server (npx @browserbasehq/mcp).


Flags & Example Configs

Proxies

Here are our docs on Proxies.

To use proxies in STDIO, set the --proxies flag in your MCP Config:

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

Advanced Stealth

Here are our docs on Advanced Stealth.

To use proxies in STDIO, set the --advancedStealth flag in your MCP Config:

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

Contexts

Here are our docs on Contexts

To use contexts in STDIO, set the --contextId flag in your MCP Config:

{ "mcpServers": { "browserbase": { "command" : "npx", "args" : ["@browserbasehq/mcp", "--contextId", "<YOUR_CONTEXT_ID>"], "env": { "BROWSERBASE_API_KEY": "", "BROWSERBASE_PROJECT_ID": "" } } } }

Why would you need to inject cookies? Our context API currently works on persistent cookies, but not session cookies. So sometimes our persistent auth might not work (we're working hard to add this functionality).

You can flag cookies into the MCP by adding the cookies.json to your MCP Config.

To use proxies in STDIO, set the --proxies flag in your MCP Config. Your cookies JSON must be in the type of Playwright Cookies

{ "mcpServers": { "browserbase" { "command" : "npx", "args" : [ "@browserbasehq/mcp", "--cookies", '{ "cookies": json, }' ], "env": { "BROWSERBASE_API_KEY": "", "BROWSERBASE_PROJECT_ID": "" } } } }

Browser Viewport Sizing

The default viewport sizing for a browser session is 1024 x 768. You can adjust the Browser viewport sizing with browserWidth and browserHeight flags.

Here's how to use it for custom browser sizing. We recommend to stick with 16:9 aspect ratios (ie: 1920 x 1080, 1280, 720, 1024 x 768)

{ "mcpServers": { "browserbase": { "command" : "npx", "args" : [ "@browserbasehq/mcp", "--browserHeight 1080", "--browserWidth 1920", ], "env": { "BROWSERBASE_API_KEY": "", "BROWSERBASE_PROJECT_ID": "" } } } }

Structure

  • src/: TypeScript source code
    • index.ts: Main entry point, env checks, shutdown
    • server.ts: MCP Server setup and request routing
    • sessionManager.ts: Handles Browserbase session creation/management
    • tools/: Tool definitions and implementations
    • resources/: Resource (screenshot) handling
    • types.ts: Shared TypeScript types
  • dist/: Compiled JavaScript output
  • tests/: Placeholder for tests
  • utils/: Placeholder for utility scripts
  • Dockerfile: For building a Docker image
  • Configuration files (.json, .ts, .mjs, .npmignore)

Contexts for Persistence

This server supports Browserbase's Contexts feature, which allows persisting cookies, authentication, and cached data across browser sessions:

  1. Creating a Context:
    browserbase_context_create: Creates a new context, optionally with a friendly name
  2. Using a Context with a Session:
    browserbase_session_create: Now accepts a 'context' parameter with: - id: The context ID to use - name: Alternative to ID, the friendly name of the context - persist: Whether to save changes (cookies, cache) back to the context (default: true)
  3. Deleting a Context:
    browserbase_context_delete: Deletes a context when you no longer need it

Contexts make it much easier to:

  • Maintain login state across sessions
  • Reduce page load times by preserving cache
  • Avoid CAPTCHAs and detection by reusing browser fingerprints

This server also provides direct cookie management capabilities:

  1. Adding Cookies:
    browserbase_cookies_add: Add cookies to the current browser session with full control over properties
  2. Getting Cookies:
    browserbase_cookies_get: View all cookies in the current session (optionally filtered by URLs)
  3. Deleting Cookies:
    browserbase_cookies_delete: Delete specific cookies or clear all cookies from the session

These tools are useful for:

  • Setting authentication cookies without navigating to login pages
  • Backing up and restoring cookie state
  • Debugging cookie-related issues
  • Manipulating cookie attributes (expiration, security flags, etc.)

TODO/Roadmap

  • Implement true ref-based interaction logic for click, type, drag, hover, select_option.
  • Implement element-specific screenshots using ref.
  • Add more standard MCP tools (tabs, navigation, etc.).
  • Add tests.
Install Server
A
security – no known vulnerabilities
A
license - permissive license
A
quality - confirmed to work

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

This server provides cloud browser automation capabilities using Browserbase, Puppeteer, and Stagehand. This server enables LLMs to interact with web pages, take screenshots, and execute JavaScript in a cloud browser environment.

  1. How to setup in MCP json
    1. To run on NPM (Recommended)
    2. To run 100% local:
    3. STDIO:
    4. SSE:
  2. Flags Explained:
    1. NOTE:
  3. Flags & Example Configs
    1. Proxies
    2. Advanced Stealth
    3. Contexts
    4. Cookie Injection
    5. Browser Viewport Sizing
  4. Structure
    1. Contexts for Persistence
      1. Cookie Management
        1. TODO/Roadmap

          Related MCP Servers

          • A
            security
            F
            license
            A
            quality
            A server that enables browser automation using Playwright, allowing interaction with web pages, capturing screenshots, and executing JavaScript in a browser environment through LLMs.
            Last updated -
            12
            9,457
            1
            TypeScript
          • A
            security
            F
            license
            A
            quality
            Enables LLMs to perform web browsing tasks, take screenshots, and execute JavaScript using Puppeteer for browser automation.
            Last updated -
            4
            15,502
            1
            JavaScript
          • A
            security
            F
            license
            A
            quality
            Enables browser automation for LLMs on Linux display servers, supporting web interaction, screenshots, and JavaScript execution in a real browser.
            Last updated -
            7
            5
            4
            JavaScript
            • Linux
          • -
            security
            A
            license
            -
            quality
            A Model Context Protocol server that enables LLMs to automate web browsers using Puppeteer, allowing navigation, screenshots, form filling, and JavaScript execution in a real browser environment.
            Last updated -
            JavaScript
            MIT License

          View all related MCP servers

          MCP directory API

          We provide all the information about MCP servers via our MCP API.

          curl -X GET 'https://glama.ai/api/mcp/v1/servers/browserbase/mcp-server-browserbase'

          If you have feedback or need assistance with the MCP directory API, please join our Discord server