seleniumbase-mcp

Overview Schema Source Related Servers Discussions Admin

Start Browser

start_browser

Idempotent

Launch a persistent browser session for automation. Call this before page interactions; the session stays active across calls until closed.

Instructions

Launch a persistent SeleniumBase Pure CDP Mode browser session.

Call this before using browser interaction tools such as open_url, get_content, click_element, 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.

First observedv0.1.0Sep 15, 2026

TDQS

A5/5.0

Behavior5/5

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

Beyond the annotations, the description discloses persistence across calls, CDP mode, automatic one retry on startup failure, reuse of cookies/tabs/history/localStorage/sessionStorage, and the fact that no second browser is launched if a session already exists. It also documents environment requirements. Nothing contradicts the annotations; idempotentHint is consistent with the already-running behavior.

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

Conciseness5/5

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

The description is long but organized into labeled sections (Args, Returns, Startup behavior, Lifecycle, Environment requirements), with purpose and usage front-loaded before parameter details. Given 8 parameters and the need to explain lifecycle and session reuse, the length is warranted and every block adds information.

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?

The definition covers return values, startup retry behavior, lifecycle/session reuse, environment prerequisites, and all parameters, while the output schema handles the exact confirmation/error shape. For a complex setup tool with 8 optional parameters, this is complete and self-sufficient.

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 Args block carries the full burden and succeeds: all 8 parameters are explained semantically, with defaults, examples, and a mutual-exclusion warning. It adds platform-specific headless defaults, use_chromium guidance for when Chrome is not installed, and proxy format examples. This fully compensates for the empty schema descriptions.

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 first sentence names a specific action (launch) and a specific resource (persistent SeleniumBase Pure CDP Mode browser session), and the lifecycle note distinguishes it from sibling interaction tools by stating it must be called before them. The CDP-versus-WebDriver note removes ambiguity about what kind of browser session is created. This is clearly differentiated from the other browser tools in the sibling list.

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 browser interaction tools such as open_url, get_content, click_element, type_text, and find_elements, and to call close_browser when finished. It also tells the agent what happens if a session is already running, covering the when-not-to-repeat case. No alternative startup tool exists among the siblings, so no further exclusion is needed.

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