Servidor MCP de SeleniumBase

Expone la automatización de navegador de SeleniumBase como herramientas a través del Model Context Protocol, para que cualquier cliente MCP (Claude Desktop, Claude Code, etc.) pueda controlar un navegador real.

Hay tres variantes de servidor en esta carpeta:

Los tres usan headless=False por defecto — la ventana del navegador es visible a menos que pases headless=True al iniciar una sesión.

Apunta la configuración de tu cliente MCP al *_server.py que se ajuste a la tarea (ver paso 3 a continuación) — o registra los tres con nombres diferentes.

1. Instalación

(Requiere Python 3.10+ y uv)

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

uv sync lee pyproject.toml, crea un .venv/ en esta carpeta e instala las dos dependencias (mcp[cli], seleniumbase) junto con este proyecto en sí — que registra tres comandos de consola-script mediante [project.scripts]:

• seleniumbase-driver

• seleniumbase-cdp

• seleniumbase-sb

Cada uno simplemente llama a la función main() de ese archivo de servidor (mcp.run(transport="stdio")). Esto es lo que permite que uv run <nombre> — sin ruta de python, sin ruta de venv, sin ruta de script — funcione como comando del cliente MCP en los pasos 3 y 4 a continuación.

# 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 tienes uv? Un python3 -m venv venv && pip install -e . normal también funciona — solo sustituye python <script>.py por uv run <nombre> en todo lo siguiente, y usa rutas absolutas de venv/bin/python + rutas de script en la configuración de tu cliente MCP en lugar de las opciones sin ruta.)

Related MCP server: gotham-browser

2. Pruébalo de forma independiente (comprobación de sanidad opcional)

uv run mcp dev cdp_server.py

Eso abre el Inspector MCP para el Servidor MCP de "Modo CDP Puro" de SeleniumBase, donde puedes probar comandos ("Tools"). Ctrl+C para salir. La prueba real es conectarlo a un cliente (siguiente paso).

3. Conéctalo a Claude Desktop

Claude Desktop no se ejecuta desde un directorio de "proyecto" como lo hace Claude Code, por lo que un uv run <nombre> simple no garantiza que encuentre este repositorio. Dos formas de obtener una configuración estable:

Opción A — instalación global (recomendada, cero rutas en cualquier lugar):

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

Esto coloca seleniumbase-driver/seleniumbase-cdp/seleniumbase-sb en tu PATH de forma permanente (ejecuta uv tool ensurepath una vez si advierte que su directorio bin no está en PATH todavía). Entonces claude_desktop_config.json puede ser simplemente:

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

Opción B — apunta uv directamente al repositorio (una ruta absoluta, pero sin ruta de venv/intérprete que rastrear, y sin paso de instalación separado):

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

La ubicación de claude_desktop_config.json depende de tu sistema:

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

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

Reinicia Claude Desktop. Deberías ver un icono de herramientas 🔨 que indica que el/los servidor(es) están conectados, con herramientas como start_browser, navigate, click, etc. disponibles. Mantén solo las entradas que realmente quieras — tres servidores separados de automatización de navegador es mucho si solo necesitas uno.

4. Conéctalo a Claude Code

El .mcp.json de este repositorio está verificado y listo para usar tal cual — sin necesidad de editar rutas, porque uv run <nombre> resuelve este proyecto desde pyproject.toml en el directorio actual:

{
  "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 carga automáticamente .mcp.json desde el directorio en el que lanzas claude, así que mientras ejecutes claude desde dentro de este repositorio (o un clon del mismo), simplemente funciona — de forma idéntica para cada compañero que clone el repositorio, con cero ediciones específicas de máquina.

Si prefieres registrar los servidores manualmente en lugar de depender de .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

(ejecutado desde dentro del directorio del repositorio, por la misma razón que arriba.)

Herramientas expuestas (driver_server.py)

Notas de diseño / cosas a adaptar para tu caso de uso

• Sesión global única. Cada servidor mantiene una sesión de navegador a la vez. Esto coincide con cómo se lanzan típicamente los servidores MCP (un proceso por conexión de cliente) y mantiene la superficie de herramientas simple. Si necesitas múltiples pestañas/sesiones de navegador concurrentes, tendrías que extender esto a un dict de sesiones nombradas y añadir un parámetro session_id a cada herramienta.

• Llamadas bloqueantes. Las llamadas de SeleniumBase son síncronas y bloquearán el servidor mientras una página carga o se espera un elemento. Para una herramienta local de un solo usuario esto está bien; para un servidor multi-cliente querrías ejecutarlas en un grupo de hilos mediante asyncio.to_thread.

• Headless vs. con ventana. El valor por defecto es con ventana (headless=False) para que puedas ver el navegador trabajar y para que los sitios que bloquean Chrome headless sigan funcionando. Pasa headless=True para uso en segundo plano/servidor una vez que hayas confirmado que un flujo funciona. El uc=True de sb_server.py (undetected-chromedriver) también ayuda contra muros de detección de bots.

Extensión

Añadir una herramienta es simplemente añadir una función decorada con @mcp.tool() que llame al método correspondiente de SeleniumBase — SeleniumBase tiene métodos para subidas de archivos, pasar el cursor, alertas, condiciones de red y más que aún no están envueltos arriba.

cdp_server.py — Modo CDP Puro

Envuelve seleniumbase.sb_cdp.Chrome, el modo más sigiloso de SeleniumBase: el navegador se controla enteramente a través del Chrome DevTools Protocol, sin WebDriver en el bucle en absoluto. Referencia: cdp_mode_methods.md.

Grupos de herramientas

Notas de diseño específicas de CDP

• Los elementos no cruzan el cable como identificadores. En el modo CDP nativo, find_element() devuelve un objeto vivo con sus propios métodos (el.click(), el.get_html(), ...). Las herramientas MCP solo pueden devolver datos serializables en JSON, por lo que find_element_info/find_all_info resuelven el elemento inmediatamente a un dict simple (tag_name, text, html) en lugar de devolver un identificador sobre el que pudieras llamar más métodos. Si necesitas actuar sobre uno de varios resultados, usa click_nth_element (actúa por posición) en lugar de "buscar y luego hacer clic" como dos pasos separados.

• La resolución de captchas no es universal. solve_captcha gestiona los tipos de desafío compatibles (p. ej., Cloudflare Turnstile en la aplicación de demostración de SeleniumBase); no es un bypass garantizado para CAPTCHAs arbitrarios.

• Finalización de sesión. sb.quit() (usado por close_browser) es la forma documentada de terminar una sesión; el navegador también se cierra automáticamente si el proceso sale sin llamarlo.

• No envueltos: los métodos gui_* basados en PyAutoGUI (excluidos por diseño — consulte las notas de diseño de nivel superior), los mecanismos internos de bajo nivel (get_websocket_url, add_handler, concesiones de permisos, get_document/get_flattened_document sin procesar) y los alias exactos de métodos (open/goto frente a get) se omitieron para mantener la lista de herramientas enfocada — agrégalos de la misma manera que cualquier otra herramienta si los necesitas.

sb_server.py — SB() sin la sentencia with

Envuelve seleniumbase.SB(), normalmente usado como administrador de contexto:

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

Las llamadas a herramientas de un servidor MCP ocurren una a la vez en invocaciones de función separadas — no hay un único bloque indentado alrededor del cual poner with —, así que este servidor invoca el protocolo del administrador de contexto manualmente:

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

sb es una instancia de BaseCase, la API más amplia de SeleniumBase — un superconjunto de lo que expone Driver (en driver_server.py), más las utilidades de sigilo del modo UC y algunos extras que driver_server.py/cdp_server.py no tienen. Este servidor se centra en esos extras en lugar de re-envolver todo lo ya cubierto:

Además, las mismas herramientas principales de navegación/interacción/espera/aserciones/cookies/ desplazamiento/pestañas/salida que los otros dos servidores, llamadas a través de los nombres de métodos de BaseCase (p. ej., sb.goto, sb.click, sb.assert_element) en lugar de los de Driver o CDP.

Notas de diseño específicas de SB()

• El modo UC (modo sigiloso) requiere uc=True al inicio. Pásalo en start_browser desde el principio si los vas a necesitar.

• activate_cdp_mode no inicia una nueva sesión. Cambia el modo subyacente de la sesión existente de sb a CDP puro para las acciones posteriores — es una escalada a mitad del flujo, no un navegador nuevo.