Skip to main content
Glama
Sign In
Playwright Browserbase MCP Server

Playwright Browserbase MCP Server

by ampcome-mcps
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript

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

Quickstarts:

Install MCP Server

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

To run on NPM (Recommended)

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!

Related MCP server: browser-use MCP Server

Flags Explained:

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

Flag

Description

--browserbaseApiKey <key>

Your Browserbase API key for authentication

--browserbaseProjectId <id>

Your Browserbase project ID

--proxies

Enable Browserbase proxies for the session

--advancedStealth

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

Cookie Injection

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

Cookie Management

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.

Available Tools

17 tools
browserbase_screenshotA

Takes a screenshot of the current page. Use this tool to learn where you are on the page when controlling the browser with Stagehand. Only use this tool when the other tools are not sufficient to get the information you need.

Inputs: name.

browserbase_session_closeA

Closes the current Browserbase session by properly shutting down the Stagehand instance, which handles browser cleanup and terminates the session recording.

Inputs: no named parameters.

browserbase_session_createA

Create or reuse a single cloud browser session using Browserbase with fully initialized Stagehand. WARNING: This tool is for SINGLE browser workflows only. If you need multiple browser sessions running simultaneously (parallel scraping, A/B testing, multiple accounts), use 'multi_browserbase_stagehand_session_create' instead. This creates one browser session with all configuration flags (proxies, stealth, viewport, cookies, etc.) and initializes Stagehand to work with that session. Updates the active session.

Inputs: sessionId.

browserbase_stagehand_actA

Performs an action on a web page element. Act actions should be as atomic and specific as possible, i.e. "Click the sign in button" or "Type 'hello' into the search input". AVOID actions that are more than one step, i.e. "Order me pizza" or "Send an email to Paul asking him to call me".

Inputs: action (required), variables.

browserbase_stagehand_extractA

Extracts structured information and text content from the current web page based on specific instructions and a defined schema. This tool is ideal for scraping data, gathering information, or pulling specific content from web pages. Use this tool when you need to get text content, data, or information from a page rather than interacting with elements. For interactive elements like buttons, forms, or clickable items, use the observe tool instead. The extraction works best when you provide clear, specific instructions about what to extract and a well-defined JSON schema for the expected output format. This ensures the extracted data is properly structured and usable.

Inputs: instruction (required).

browserbase_stagehand_get_all_urlsA

Gets the current URLs of all active browser sessions. Returns a mapping of session IDs to their current URLs.

Inputs: no named parameters.

browserbase_stagehand_get_urlA

Gets the current URL of the browser page. Returns the complete URL including protocol, domain, path, and any query parameters or fragments.

Inputs: no named parameters.

browserbase_stagehand_navigateA

Navigate to a URL in the browser. Only use this tool with URLs you're confident will work and stay up to date. Otherwise, use https://google.com as the starting point

Inputs: url (required).

browserbase_stagehand_observeA

Observes and identifies specific interactive elements on the current web page that can be used for subsequent actions. This tool is specifically designed for finding actionable (interactable) elements such as buttons, links, form fields, dropdowns, checkboxes, and other UI components that you can interact with. Use this tool when you need to locate elements before performing actions with the act tool. DO NOT use this tool for extracting text content or data - use the extract tool instead for that purpose. The observe tool returns detailed information about the identified elements including their properties, location, and interaction capabilities. This information can then be used to craft precise actions. The more specific your observation instruction, the more accurate the element identification will be. Think of this as your 'eyes' on the page to find exactly what you need to interact with.

Inputs: instruction (required), returnAction.

multi_browserbase_stagehand_act_sessionB

Performs an action on a web page element. Act actions should be as atomic and specific as possible, i.e. "Click the sign in button" or "Type 'hello' into the search input". AVOID actions that are more than one step, i.e. "Order me pizza" or "Send an email to Paul asking him to call me". (for a specific session)

Inputs: sessionId (required), action (required), variables.

multi_browserbase_stagehand_extract_sessionA

Extracts structured information and text content from the current web page based on specific instructions and a defined schema. This tool is ideal for scraping data, gathering information, or pulling specific content from web pages. Use this tool when you need to get text content, data, or information from a page rather than interacting with elements. For interactive elements like buttons, forms, or clickable items, use the observe tool instead. The extraction works best when you provide clear, specific instructions about what to extract and a well-defined JSON schema for the expected output format. This ensures the extracted data is properly structured and usable. (for a specific session)

Inputs: sessionId (required), instruction (required).

multi_browserbase_stagehand_get_url_sessionA

Gets the current URL of the browser page. Returns the complete URL including protocol, domain, path, and any query parameters or fragments. (for a specific session)

Inputs: sessionId (required).

multi_browserbase_stagehand_navigate_sessionA

Navigate to a URL in the browser. Only use this tool with URLs you're confident will work and stay up to date. Otherwise, use https://google.com as the starting point (for a specific session)

Inputs: sessionId (required), url (required).

multi_browserbase_stagehand_observe_sessionA

Observes and identifies specific interactive elements on the current web page that can be used for subsequent actions. This tool is specifically designed for finding actionable (interactable) elements such as buttons, links, form fields, dropdowns, checkboxes, and other UI components that you can interact with. Use this tool when you need to locate elements before performing actions with the act tool. DO NOT use this tool for extracting text content or data - use the extract tool instead for that purpose. The observe tool returns detailed information about the identified elements including their properties, location, and interaction capabilities. This information can then be used to craft precise actions. The more specific your observation instruction, the more accurate the element identification will be. Think of this as your 'eyes' on the page to find exactly what you need to interact with. (for a specific session)

Inputs: sessionId (required), instruction (required), returnAction.

multi_browserbase_stagehand_session_closeA

Cleanup parallel session for multi-session workflows. Properly terminates a browser session, ends the Browserbase session, and frees cloud resources. Always use this when finished with a session to avoid resource waste and billing charges. Critical for responsible multi-session automation - each unclosed session continues consuming resources!

Inputs: sessionId (required).

multi_browserbase_stagehand_session_createA

Create parallel browser session for multi-session workflows. Use this when you need multiple browser instances running simultaneously: parallel data scraping, concurrent automation, A/B testing, multiple user accounts, cross-site operations, batch processing, or any task requiring more than one browser. Creates an isolated browser session with independent cookies, authentication, and state. Always pair with session-specific tools (those ending with '_session'). Perfect for scaling automation tasks that require multiple browsers working in parallel.

Inputs: name, browserbaseSessionID.

multi_browserbase_stagehand_session_listA

ONLY WORKS WITH MULTI-SESSION TOOLS! Track all parallel sessions: Critical tool for multi-session management! Shows all active browser sessions with their IDs, names, ages, and Browserbase session IDs. Use this frequently to monitor your parallel automation workflows, verify sessions are running, and get session IDs for session-specific tools. Essential for debugging and resource management in complex multi-browser scenarios.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A3.9/5.0

    Scored across 17 tools

    Disambiguation4/5

    Most tools have distinct purposes, with clear separation between single-session and multi-session variants, and between action (act), observation (observe), extraction (extract), navigation, and session management. However, there is some potential confusion between browserbase_stagehand_act and multi_browserbase_stagehand_act_session, as they perform identical functions but for different session contexts, which could lead to misselection if the agent doesn't track session state properly.

    Naming Consistency3/5

    The naming follows a consistent snake_case pattern and uses descriptive terms like 'act', 'extract', 'observe', 'navigate', and 'session'. However, there is inconsistency in the prefixing: some tools start with 'browserbase_' while others start with 'multi_browserbase_', and the suffix '_session' is inconsistently applied (e.g., multi_browserbase_stagehand_act_session vs. browserbase_stagehand_act). This mixed convention reduces predictability.

    Tool Count4/5

    With 17 tools, the count is on the higher side but reasonable for a browser automation server that supports both single and multi-session workflows. It covers core functionalities like navigation, interaction, extraction, and session management, but it feels slightly heavy due to the duplication of tools for single vs. multi-session contexts, which could have been streamlined.

    Completeness5/5

    The tool set provides comprehensive coverage for browser automation, including session creation, closure, and listing; navigation; interaction (act and observe); data extraction; and URL retrieval. It supports both single and parallel workflows, with clear guidance on when to use each tool. No obvious gaps are present for the stated purpose of controlling browsers with Stagehand.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers

    • browser-use MCP Server

      williamvd4
      F
      license
      Not graded
      quality
      Not graded
      maintenance
      MCP server enabling LLMs to perform browser tasks via SSE transport, allowing clients like Cursor.ai and Claude to open websites and interact with web content through natural language commands.
      1
      -

    • agent-browser-mcp

      minhlucvan
      A
      license
      B
      quality
      D
      maintenance
      An MCP server that provides browser automation capabilities, enabling LLMs to control a web browser for navigation, interaction, and data extraction.
      32
      111 npm
      14
      MIT

    • Browser MCP Server Template

      ZuccaMuka
      A
      license
      Not graded
      quality
      D
      maintenance
      A browser automation MCP server with stealth mode, profile management, and multi-browser support, enabling LLMs to control browsers for tasks like navigation, data extraction, and form filling.
      11 npm
      1
      MIT

    Appeared in Searches