seleniumbase-mcp

Official

Overview Schema Source Related Servers Discussions Admin

start_browser

Launch a persistent browser session for automation, preserving cookies, tabs, and state across subsequent tool calls until closed.

Instructions

Launch a persistent SeleniumBase Pure CDP Mode browser session.

Call this before using 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 controls the browser through the Chrome DevTools Protocol (CDP), not WebDriver.

Args: url: Optional URL to navigate to during browser startup. When provided, the tool waits for the browser launch/navigation operation to complete before returning. If omitted, the browser starts without navigating to a specified URL.

headless: Controls whether the browser runs without a visible window.
    True forces headless mode; False forces headed mode. If None, this
    tool defaults to headless on Linux and headed on Windows/macOS.

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: Optional path to the browser executable.
    Use this when the desired browser is installed at a non-standard
    location. Mutually exclusive with use_chromium.

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, or a descriptive error if the browser startup fails.

Startup behavior: If the initial launch fails, the tool automatically retries once.

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. If a browser session is already running, this tool does not launch another browser and instead returns a message indicating that the existing session is active.

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.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`url`	No
`guest`	No
`proxy`	No
`ad_block`	No
`headless`	No
`incognito`	No
`use_chromium`	No
`browser_executable_path`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv1.3.1Sep 10, 2026
- removedInput schema / properties / headless / anyOf
```
Removed value: -[
-  {
-    "type": "boolean"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedInput schema / properties / headless / enum
```
Added value: +[
+  false,
+  true,
+  null
+]
```
Changed3 schema fields changedv1.2.1Sep 1, 2026
- 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"
```

Changed2 schema fields changedv1.2.0Aug 31, 2026

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"
+}

Changed5 schema fields changedv1.0.2Aug 30, 2026

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"
+}

First observedv0.1.1Aug 23, 2026

TDQS

A4.9/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 and excels: it discloses session persistence via CDP rather than WebDriver, the automatic single retry on launch failure, platform-specific headless defaults, and the fact that an existing session is reused. It also covers return behavior and environment prerequisites, which is exemplary for a tool with zero structured annotations.

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 long but the length is largely justified by 8 parameters and important lifecycle/environment context. It is well-sectioned and front-loaded with the core purpose, though there is minor redundancy in the lifecycle section that could be trimmed without loss.

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?

Given the tool's complexity—8 optional parameters, platform-dependent behavior, and session lifecycle responsibilities—the description provides everything an agent needs: when to invoke, how to resolve missing browser discovery, what happens on retry, and how state persists. The output schema covers return values, so the brief Return section is appropriate.

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 must compensate, and it documents all 8 parameters in an Args section with meaningful details. It adds mutual-exclusion guidance (browser_executable_path vs use_chromium), a warning not to combine guest with incognito=True, and practical examples for proxy formats.

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 opens with a specific verb and resource: 'Launch a persistent SeleniumBase Pure CDP Mode browser session.' It clearly distinguishes itself from sibling interaction tools such as navigate and click by framing it as the prerequisite startup step, making its role unambiguous.

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

Usage Guidelines5/5

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

The description explicitly says to call this before using browser interaction tools such as navigate, get_content, click, type_text, or find_elements, and to call close_browser when finished. It also explains that if a session is already running, the tool does not launch another one, giving an agent clear routing and lifecycle guidance.

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