SeleniumBase MCP Server

Macht SeleniumBase-Browserautomatisierung als Tools über das Model Context Protocol verfügbar, sodass jeder MCP-Client (Claude Desktop, Claude Code, etc.) einen echten Browser steuern kann.

In diesem Ordner gibt es drei Server-Varianten:

Alle drei verwenden standardmäßig headless=False — das Browserfenster ist sichtbar, es sei denn, du übergibst headless=True beim Start einer Sitzung.

Richte deine MCP-Client-Konfiguration auf das passende *_server.py aus (siehe Schritt 3 unten) — oder registriere alle drei unter verschiedenen Namen.

1. Installation

(Erfordert Python 3.10+ und uv)

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

uv sync liest pyproject.toml, erstellt einen .venv/-Ordner in diesem Verzeichnis und installiert die beiden Abhängigkeiten (mcp[cli], seleniumbase) zusammen mit diesem Projekt selbst — was über [project.scripts] drei Console-Script-Befehle registriert:

• seleniumbase-driver

• seleniumbase-cdp

• seleniumbase-sb

Jeder davon ruft lediglich die main()-Funktion der jeweiligen Server-Datei auf (mcp.run(transport="stdio")). Deshalb funktioniert uv run <name> — ohne Python-Pfad, ohne Venv-Pfad, ohne Skript-Pfad — als Befehl für den MCP-Client in den Schritten 3 und 4 weiter unten.

# 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.)

(Kein uv? Ein normales python3 -m venv venv && pip install -e . funktioniert auch — ersetze dann einfach uv run <name> durch python <skript>.py und verwende in deiner MCP-Client-Konfiguration absolute Pfade zu bin/python und den Skripten anstelle der pfadlosen Optionen.)

Related MCP server: gotham-browser

2. Eigenständig testen (optionaler Sanity-Check)

uv run mcp dev cdp_server.py

Das öffnet den MCP Inspector für den „Pure CDP Mode" von SeleniumBase, wo du die Tools testen kannst. Ctrl+C zum Beenden. Der eigentliche Test ist die Anbindung im nächsten Schritt.

3. Mit Claude Desktop verbinden

Claude Desktop läuft nicht aus einem bestimmten Projektverzeichnis heraus wie Claude Code, daher findet ein nacktes uv run <name> dieses Repository nicht unbedingt. Zwei Möglichkeiten für eine stabile Konfiguration:

Option A — global installieren (empfohlen, null Pfade überall):

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

Das legt seleniumbase-driver/seleniumbase-cdp/seleniumbase-sb dauerhaft auf deinen PATH (falls uv tool ensurepath eine Warnung ausgibt, dass das bin-Verzeichnis nicht auf dem PATH liegt, einmal ausführen). Danach kann claude_desktop_config.json so aussehen:

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

Option B — uv direkt auf das Repo zeigen lassen (ein absoluter Pfad, aber kein aufzuspürender Venv-/Interpreter-Pfad und kein separater Installationsschritt):

{
  "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"]
    }
  }
}

Der Speicherort von claude_desktop_config.json hängt vom Betriebssystem ab:

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

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

Starte Claude Desktop neu. Du solltest ein 🔨-Symbol sehen, das anzeigt, dass der/die Server verbunden sind, mit Tools wie start_browser, navigate, click usw. Behalte nur die Einträge, die du tatsächlich brauchst — drei getrennte Server sind viel, wenn du nur einen benötigst.

4. Mit Claude Code verbinden

Das .mcp.json in diesem Repo ist eingecheckt und sofort einsatzbereit — uv run <name> findet bei claude aus diesem Verzeichnis heraus automatisch die Projektkonfiguration in pyproject.toml:

{
  "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 lädt .mcp.json automatisch, wenn du claude aus diesem Repository heraus startest — identisch für jedes Teammitglied, ohne maschinenspezifische Anpassungen.

Wenn du dich nicht auf .mcp.json verlassen möchtest, kannst du den Server auch explizit registrieren:

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

Werkzeuge (driver_server.py)

(Weitere Tools siehe unten: driver_server.py und sb_server.py decken den Großteil der SeleniumBase-API ab.)

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

Die Datei claude_desktop_config.json befindet sich je nach System an folgenden Orten:

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

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

Starte Claude Desktop neu. Du solltest ein 🔨-Werkzeugsymbol sehen, das anzeigt, dass der Server verbunden ist, mit Tools wie start_browser, navigate, click usw. Behalte nur die Einträge, die du wirklich brauchst — drei Server sind viel, wenn du nur einen brauchst.

Option B: uv direkt auf das Repo zeigen lassen (ein absoluter Pfad, aber kein Venv-/Interpreter-Pfad zum Aufspüren, und kein separater Installationsschritt):

{
  "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"]
    }
  }
}

Der Speicherort von claude_desktop_config.json hängt vom Betriebssystem ab:

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

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

Starte Claude Desktop neu. Es sollte eine 🔨-Anzeige erscheinen, dass der/die Server verbunden sind, mit Tools wie start_browser, navigate, click usw. Behalte nur die Einträge, die du wirklich brauchst — drei verschiedene Automatisierungs-Server ist eine Menge, wenn du nur einen brauchst.

4. Mit Claude Code verwenden

Richte .mcp.json so ein, dass es auf dieses Repository verweist:

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

(führe claude im Stammverzeichnis dieses Repositorys aus, damit uv run <name> die lokale pyproject.toml findet.)

{
  "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 liest beim Start automatisch das .mcp.json aus dem aktuellen Verzeichnis, sodass die Tools sofort verfügbar sind, wenn du claude aus diesem Projektordner startest. Für ein Team, das das Repository klont, genügt die mitgelieferte .mcp.json – alle erhalten dieselben MCP-Server.

Verfügbare Tools (Beispiele)

Die vollständige, aktuelle Liste findest du in den Docstrings der Tools in jeder *_server.py-Datei. Einige wichtige Beispiele:

Wichtig: Die Sitzung ist global — ein Tool-Aufruf startet den Browser, alle weiteren Tools arbeiten in derselben Sitzung weiter, bis close_browser aufgerufen wird.

Migrationshinweise / bekannte Limitierungen

• Die MCP-Tools sind synchron — bei langlaufenden Aufrufen (wait, solve_captcha) hängt der MCP-Prozess. Für produktive/parallele Nutzung müsstest du sie asynchron ausführen (z. B. über asyncio.to_thread).

• Alle Server teilen sich eine einzige globale Sitzung: Wenn du mehrere Tabs/Profile parallel brauchst, musst du die Server mehrmals mit unterschiedlichen Namen registrieren.

• sb_server.py erwartet, dass die SB()-Instanz manuell betreten und verlassen wird (nicht mit with). Das ist beabsichtigt — es erlaubt den Wechsel in den CDP-Modus mitten im Ablauf und macht die Tool-Schnittstelle für MCP sauber. Der Server ruft SB().__enter__() beim ersten Tool-Aufruf auf und __exit__() bei end_session.

cdp_server.py — Pure CDP Mode

Kapselt seleniumbase.sb_cdp.Chrome, den heimlichsten Modus von SeleniumBase: Der Browser wird vollständig über das Chrome DevTools Protocol gesteuert, ganz ohne WebDriver. Referenz: cdp_mode_methods.md.

Tool-Gruppen

Design-Hinweise / Erläuterungen

• Eine einzige globale Sitzung. Das entspricht dem typischen MCP-Muster (ein Prozess pro Client-Verbindung) und hält die Server einfach. Für mehrere parallele Browser könntest du ein Dict von Sitzungen verwalten und jede *_server.py-Datei um einen Sitzungs-Parameter erweitern.

• Client-triggerte Zustandsänderungen. Wrapper wie start_browser, navigate, click etc. rufen die jeweiligen SeleniumBase-Methoden auf. Die SB()-Kontextmanager-Äquivalente werden manuell aufgerufen, damit eine einzelne Sitzung über mehrere Tool-Aufrufe hinweg bestehen bleibt.

• Keine automatische Implizit-Wartezeit. Wartezeiten sind explizit über die *wait*-Tools. SeleniumBase kann optional automatische Waits aktivieren (uc_connect_and_manage / uc), aber das bleibt dir überlassen.

• Headless/undetected: Für undetected Modus uc_connect_and_manage anstelle von Chrome verwenden (siehe Doku). headless=True wird unterstützt, kann aber von Bot-Erkennungsseiten erkannt werden.

• Kein SeleniumBase-with-Block erforderlich. self.sb ist eine Live-Instanz; alle Aktionen werden sofort ausgeführt, und die Sitzung bleibt bis close_browser bestehen.

3. Client-Konfiguration (Claude Desktop, Claude Code, curl …)

Da jeder Server hier über stdio (JSON-RPC) spricht, kannst du jeden MCP-fähigen Client mit einem mcpServers-Eintrag anbinden. Der Befehl muss uv run + den jeweiligen Serverpfad nutzen, damit das Projekt-Setup (.venv, Abhängigkeiten) verwendet wird.

Beispiel für Claude Desktop (claude_desktop_config.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

Beispiel für Claude Code (claude mcp add)

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

Rohes JSON (z. B. für generische Clients)

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

4. Verfügbare Tools (MCP)

Das hier ist die serverseitige MCP-Tool-Liste für alle drei Server, da die Methodensignaturen weitgehend identisch sind. Der tatsächliche Umfang hängt vom gewählten Dienst ab.

4. Sicherheitshinweise (wichtig)

⚠️ Dieses Paket erlaubt die Ausführung von beliebigem JavaScript und WebDriver-Befehlen. Es ist ein Werkzeug für automatisierte Tests und Web-Scraping und sollte nicht als vertrauenswürdige Sandbox betrachtet werden.

Die Tools akzeptieren direkt Selektoren, Skripte und URLs. Wenn du das über eine öffentlich zugängliche API bereitstellst, validiere und beschränke die Eingaben, um Missbrauch zu verhindern.

Installiere es nur in vertrauenswürdigen Umgebungen und nicht in kritischen Systemen.

5. Fehlerbehebung

CDP-Modus nutzen (wichtig für Bot-Schutz)

self.sb.activate_cdp_mode(url) wechselt von Standard-WebDriver auf den CDP-Modus. Das ist nützlich, wenn eine Website Bot-Erkennung einsetzt, die normales WebDriver blockiert.

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

Beispiel-Claude-Desktop-Konfiguration (alle drei Server)

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

• Elemente werden nicht als Handles über die Leitung geschickt. Im nativen CDP-Modus gibt find_element() ein Live-Objekt mit eigenen Methoden zurück (el.click(), el.get_html(), ...). MCP-Tools können nur JSON-serialisierbare Daten zurückgeben, daher lösen find_element_info/find_all_info das Element sofort in ein einfaches Dict auf (tag_name, text, html), anstatt ein Handle zurückzugeben, auf dem du weitere Methoden aufrufen könntest. Wenn du auf eines von mehreren Treffern reagieren musst, verwende click_nth_element (agiert nach Position) anstatt „finden, dann klicken“ als zwei getrennte Schritte.

• Captcha-Lösung ist nicht universell. solve_captcha behandelt unterstützte Challenge-Typen (z. B. Cloudflare Turnstile in der SeleniumBase-Demo-App); es ist kein garantierter Bypass für beliebige CAPTCHAs.

• Session-Teardown. sb.quit() (verwendet von close_browser) ist der dokumentierte Weg, eine Sitzung zu beenden; der Browser schließt sich auch automatisch, wenn der Prozess ohne ihn beendet wird.

• Nicht umfasst: PyAutoGUI-basierte gui_*-Methoden (bewusst ausgeschlossen – siehe die Design-Hinweise auf oberster Ebene), Low-Level-Interna (get_websocket_url, add_handler, Berechtigungserteilungen, rohes get_document/get_flattened_document) und exakte Methoden-Aliasse (open/goto vs. get) wurden weggelassen, um die Tool-Liste fokussiert zu halten – füge sie auf die gleiche Weise wie jedes andere Tool hinzu, wenn du sie benötigst.

sb_server.py — SB() ohne die with-Anweisung

Umschließt seleniumbase.SB(), normalerweise als Kontextmanager verwendet:

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

Die Tool-Aufrufe eines MCP-Servers erfolgen einzeln über separate Funktionsaufrufe – es gibt keinen einzelnen eingerückten Block, um with darum zu legen – daher ruft dieser Server das Kontextmanager-Protokoll stattdessen manuell auf:

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

sb ist eine BaseCase-Instanz, die breiteste API von SeleniumBase – eine Obermenge dessen, was Driver (in driver_server.py) bereitstellt, plus UC-Mode-Stealth-Helfer und ein paar Extras, die driver_server.py/cdp_server.py nicht haben. Dieser Server konzentriert sich auf diese Extras, anstatt alles bereits Abgedeckte erneut zu umschließen:

Plus die gleichen Kernwerkzeuge für Navigation/Interaktion/Warten/Assertions/Cookies/Scrollen/Tabs/Ausgabe wie die anderen beiden Server, aufgerufen über die BaseCase-Methodennamen (z. B. sb.goto, sb.click, sb.assert_element) statt über die von Driver oder CDP.

SB()-spezifische Design-Hinweise

• UC-Modus (Stealth-Modus) erfordert uc=True beim Start. Übergib es vorab in start_browser, falls du es benötigst.

• activate_cdp_mode startet keine neue Sitzung. Es wechselt den zugrunde liegenden Modus der bestehenden sb-Sitzung für nachfolgende Aktionen zu Pure CDP – es ist eine Eskalation mitten im Ablauf, kein neuer Browser.