SeleniumBase MCP Server

Exposes SeleniumBase browser automation as tools over the Model Context Protocol, so any MCP client (Claude Desktop, Claude Code, etc.) can drive a real browser.

There are three server variants in this folder:

All three default headless=False — the browser window is visible unless you pass headless=True when starting a session.

Point your MCP client config at whichever *_server.py fits the task (see step 3 below) — or register all three under different names.

1. Install

(Requires Python 3.10+ and uv)

git clone https://github.com/seleniumbase/seleniumbase-mcp.git
cd seleniumbase-mcp
uv sync

uv sync reads pyproject.toml, creates a .venv/ in this folder, and installs the two dependencies (mcp[cli], seleniumbase) along with this project itself — which registers three console-script commands via [project.scripts]:

• seleniumbase-driver

• seleniumbase-cdp

• seleniumbase-sb

Each just calls that server file's main() function (mcp.run(transport="stdio")). This is what lets uv run <name> — no python path, no venv path, no script path — work as the MCP client command in steps 3 and 4 below.

# SeleniumBase's Driver() and SB() formats need a browser driver downloaded:
uv run seleniumbase get chromedriver
# (Not needed for the "seleniumbase-cdp" Pure CDP Mode MCP Server,
#  which doesn't use WebDriver at all.)

(No uv? A regular python3 -m venv venv && pip install -e . works too — just substitute python <script>.py for uv run <name> everywhere below, and use absolute venv/bin/python + script paths in your MCP client config instead of the path-free options.)

Related MCP server: gotham-browser

2. Try it standalone (optional sanity check)

uv run mcp dev cdp_server.py

That opens the MCP Inspector for SeleniumBase's "Pure CDP Mode" MCP Server, where you can test commands ("Tools"). Ctrl+C to exit. The real test is wiring it into a client (next step).

3. Connect it to Claude Desktop

Claude Desktop doesn't run from a "project" directory the way Claude Code does, so a bare uv run <name> isn't guaranteed to find this repo. Two ways to get a stable config:

Option A — global install (recommended, zero paths anywhere):

uv tool install .          # from inside the repo, installs the 3 commands globally

This puts seleniumbase-driver/seleniumbase-cdp/seleniumbase-sb on your PATH permanently (run uv tool ensurepath once if it warns that its bin directory isn't on PATH yet). Then claude_desktop_config.json can be just:

{
  "mcpServers": {
    "seleniumbase-cdp": { "command": "seleniumbase-cdp" },
    "seleniumbase-driver": { "command": "seleniumbase-driver" },
    "seleniumbase-sb": { "command": "seleniumbase-sb" }
  }
}

Option B — point uv at the repo directly (one absolute path, but no venv/interpreter path to track down, and no separate install step):

{
  "mcpServers": {
    "seleniumbase-cdp": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/seleniumbase-mcp", "run", "seleniumbase-cdp"]
    },
    "seleniumbase-driver": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/seleniumbase-mcp", "run", "seleniumbase-driver"]
    },
    "seleniumbase-sb": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/seleniumbase-mcp", "run", "seleniumbase-sb"]
    }
  }
}

The location of claude_desktop_config.json depends on your system:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

Restart Claude Desktop. You should see a 🔨 tools icon indicating the server(s) connected, with tools like start_browser, navigate, click, etc. available. Only keep the entries you actually want — three separate browser-automation servers is a lot if you only need one.

4. Connect it to Claude Code

This repo's .mcp.json is checked in and ready to use as-is — no path editing required, because uv run <name> resolves this project from pyproject.toml in the current directory:

{
  "mcpServers": {
    "seleniumbase-cdp": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "seleniumbase-cdp"]
    },
    "seleniumbase-driver": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "seleniumbase-driver"]
    },
    "seleniumbase-sb": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "seleniumbase-sb"]
    }
  }
}

Claude Code auto-loads .mcp.json from the directory you launch claude in, so as long as you run claude from inside this repo (or a clone of it), it just works — identically for every teammate who clones the repo, with zero machine-specific editing.

If you'd rather register the servers manually instead of relying on .mcp.json:

claude mcp add seleniumbase-cdp -- uv run seleniumbase-cdp
claude mcp add seleniumbase-driver -- uv run seleniumbase-driver
claude mcp add seleniumbase-sb -- uv run seleniumbase-sb

(run from inside the repo directory, for the same reason as above.)

Tools exposed (driver_server.py)

Design notes / things to adapt for your use case

• Single global session. Each server holds one browser session at a time. This matches how MCP servers are typically launched (one process per client connection) and keeps the tool surface simple. If you need multiple concurrent browser tabs/sessions, you'd extend this to a dict of named sessions and add a session_id parameter to each tool.

• Blocking calls. SeleniumBase's calls are synchronous and will block the server while a page loads or an element is waited on. For a single-user local tool this is fine; for a multi-client server you'd want to run them in a thread pool via asyncio.to_thread.

• Headless vs Headed. Default is headed (headless=False) so you can watch the browser work and so sites that block headless Chrome still function. Pass headless=True for background/server use once you've confirmed a flow works. sb_server.py's uc=True (undetected- chromedriver) also helps against bot-detection walls.

Extending

Adding a tool is just adding a @mcp.tool()-decorated function that calls the matching SeleniumBase method — SeleniumBase has methods for file uploads, hovering, alerts, network conditions, and more that aren't wrapped above yet.

cdp_server.py — Pure CDP Mode

Wraps seleniumbase.sb_cdp.Chrome, SeleniumBase's stealthiest mode: the browser is driven entirely over the Chrome DevTools Protocol, no WebDriver in the loop at all. Reference: cdp_mode_methods.md.

Tool groups

CDP-specific design notes

• Elements don't cross the wire as handles. In native CDP Mode, find_element() returns a live object with its own methods (el.click(), el.get_html(), ...). MCP tools can only return JSON-serializable data, so find_element_info/find_all_info resolve the element immediately to a plain dict (tag_name, text, html) instead of returning a handle you could call further methods on. If you need to act on one of several matches, use click_nth_element (acts by position) rather than "find, then click" as two separate steps.

• Captcha solving isn't universal. solve_captcha handles supported challenge types (e.g. Cloudflare Turnstile in the SeleniumBase demo app); it isn't a guaranteed bypass for arbitrary CAPTCHAs.

• Session teardown. sb.quit() (used by close_browser) is the documented way to end a session; the browser also auto-closes if the process exits without it.

• Not wrapped: PyAutoGUI-based gui_* methods (excluded by design — see the top-level design notes), low-level plumbing (get_websocket_url, add_handler, permission grants, raw get_document/get_flattened_document), and exact method aliases (open/goto vs get) were left out to keep the tool list focused — add them the same way as any other tool if you need them.

sb_server.py — SB() without the with statement

Wraps seleniumbase.SB(), normally used as a context manager:

with SB(uc=True) as sb:
    sb.goto(...)

An MCP server's tool calls happen one at a time across separate function invocations — there's no single indented block to put with around — so this server calls the context manager protocol manually instead:

sb_context = SB(**kwargs)
sb = sb_context.__enter__()   # in start_browser
...
sb_context.__exit__(None, None, None)   # in close_browser

sb is a BaseCase instance, SeleniumBase's broadest API — a superset of what Driver (in driver_server.py) exposes, plus UC Mode stealth helpers and a few extras driver_server.py/cdp_server.py don't have. This server focuses on those extras rather than re-wrapping everything already covered:

Plus the same core navigation/interaction/waiting/assertions/cookies/ scrolling/tabs/output tools as the other two servers, called through the BaseCase method names (e.g. sb.goto, sb.click, sb.assert_element) rather than Driver's or CDP's.

SB()-specific design notes

• UC Mode (stealth mode) requires uc=True at startup. Pass it in start_browser up front if you'll need them.

• activate_cdp_mode doesn't start a new session. It switches the existing sb session's underlying mode to Pure CDP for subsequent actions — it's a mid-flow escalation, not a fresh browser.