Skip to main content
Glama
seleniumbase

seleniumbase-mcp

Official
by seleniumbase
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

start_browser

Launches a persistent Chrome/Chromium session via CDP for browser automation. Call this first to enable navigation, clicks, and content extraction in subsequent operations.

Instructions

Launch a persistent SeleniumBase Pure CDP Mode browser session.

This must be called before browser interaction tools such as navigate, get_content, click, type_text, or find_elements. The same browser session remains active across subsequent MCP tool calls until close_browser is called or the server process exits.

Pure CDP Mode communicates directly with the browser through the Chrome DevTools Protocol rather than WebDriver. This provides SeleniumBase's CDP-based browser automation capabilities without using WebDriver as the browser-control layer.

Args: url: Optional URL to open immediately after the browser launches. If omitted, the browser starts without navigating to a requested page.

headless: Controls whether the browser runs without a visible window.
    If True, always run headless. If False, always run headed.
    If omitted (None), the default depends on the operating system:
    Linux defaults to headless because MCP/server environments
    commonly do not have a graphical desktop, while Windows and macOS
    default to headed so that a visible browser window is available.
    Use True or False to explicitly override the OS-specific default
    on any operating system.

use_chromium: Use Chromium instead of Google Chrome. This is useful
    when Google Chrome is not installed. SeleniumBase can manage the
    Chromium browser when this option is enabled.

browser_executable_path: Explicit filesystem path to the browser
    executable when it is not installed in a standard location.
    Do not combine this with use_chromium=True.

incognito: Launch Chrome/Chromium in incognito mode.

guest: Launch Chrome/Chromium in guest mode. Do not combine this with
    incognito=True.

ad_block: Enable SeleniumBase's basic ad-blocking functionality.

proxy: Optional proxy server. Examples include
    "SERVER:PORT" or "USER:PASS@SERVER:PORT".

Returns: A confirmation message when the browser starts successfully, including the effective headless setting, or a descriptive error when browser startup fails.

Lifecycle: Call start_browser once at the beginning of a browser automation workflow. Reusing the existing session preserves cookies, tabs, navigation history, localStorage/sessionStorage, and other browser state between tool calls. Call close_browser when finished.

Environment requirements: The MCP runtime must have a compatible Chrome or Chromium browser available. If the browser executable cannot be discovered, use use_chromium=True or provide browser_executable_path explicitly.

On Linux, the default is headless=True so the browser can run in
typical server/container environments without a graphical desktop.
Set headless=False when a graphical display is available and a visible
browser is desired. On Windows and macOS, the default is
headless=False. Set headless=True when running without a desktop or
when a visible browser window is not desired.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
urlNo
guestNo
proxyNo
ad_blockNo
headlessNo
incognitoNo
use_chromiumNo
browser_executable_pathNo

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. Changed3 schema fields changedv1.2.1
    • addedInput schema / properties / headless / anyOf
      Added value: +[
+  {
+    "type": "boolean"
+  },
+  {
+    "type": "null"
+  }
+]
    • changedInput schema / properties / headless / default
      Previous value: -falseNew value: +null
    • removedInput schema / properties / headless / type
      Removed value: -"boolean"
  2. Changed2 schema fields changedv1.2.0
    • addedInput schema / properties / browser_executable_path
      Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Browser Executable Path"
+}
    • addedInput schema / properties / use_chromium
      Added value: +{
+  "default": false,
+  "title": "Use Chromium",
+  "type": "boolean"
+}
  3. Changed5 schema fields changedv1.0.2
    • removedInput schema / properties / browser
      Removed value: -{
-  "default": "chrome",
-  "title": "Browser",
-  "type": "string"
-}
    • addedInput schema / properties / guest
      Added value: +{
+  "default": false,
+  "title": "Guest",
+  "type": "boolean"
+}
    • removedInput schema / properties / guest_mode
      Removed value: -{
-  "default": false,
-  "title": "Guest Mode",
-  "type": "boolean"
-}
    • removedInput schema / properties / uc
      Removed value: -{
-  "default": true,
-  "title": "Uc",
-  "type": "boolean"
-}
    • addedInput schema / properties / url
      Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Url"
+}
  4. First observedv0.1.1

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It thoroughly explains the persistent session, state preservation, CDP communication, OS-specific headless defaults, and environment prerequisites. It also describes return values and error behavior, leaving no ambiguity about side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-organized with clear sections (Args, Returns, Lifecycle, Environment) and every section earns its place. However, the headless default explanation is repeated nearly verbatim in Args and Environment sections, adding minor redundancy. Overall, it remains focused and informative.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

This tool has 8 parameters, no annotations, and no schema description coverage, so the description must cover a lot. It addresses all parameters, lifecycle, environment, return values, and failure behavior. For a tool that establishes a persistent browser session, the description is exceptionally complete and leaves no critical gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description fully compensates by explaining each parameter's purpose, default behavior, and constraints. It even warns against combining mutually exclusive parameters (use_chromium with browser_executable_path, incognito with guest) and gives proxy format examples, adding significant value beyond the raw schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action: launching a persistent SeleniumBase Pure CDP Mode browser session. It distinguishes this tool by defining the session lifecycle and its role as a prerequisite for other browser interaction tools, so an agent can easily tell it apart from siblings like navigate or close_browser.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states when to use the tool ('must be called before browser interaction tools') and when to close it ('call close_browser when finished'), plus environment requirements. However, it does not mention what happens if the tool is called again while a session already exists, which is a minor gap in usage guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server

Other Tools

Latest Blog Posts

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/seleniumbase/seleniumbase-mcp'

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