stealth-chrome-devtools-mcp

Servidor MCP de automatización de navegador indetectable construido sobre nodriver (basado en CDP) con evasión anti-bot, sesiones de inicio de sesión persistentes y gestión de cookies.

GitHub

Prueba este MCPPatrocinado

Documentación

Stealth Chrome DevTools MCP

Automatización de navegador indetectable para agentes de IA mediante el Protocolo de Contexto de Modelo.

Un servidor MCP de Stealth Chrome DevTools autónomo con gestión inteligente de perfiles, filtrado de argumentos stealth anti-detección y manejo robusto del ciclo de vida de procesos. Construido sobre nodriver (basado en CDP) para evasión completa de anti-bots.

Demostraciones

Bypass de Cloudflare Turnstile

https://github.com/user-attachments/assets/c4de61ae-6878-4fff-9bfd-65cdd4fadc2f

Ver en YouTube

Sesiones de inicio de sesión persistentes

https://github.com/user-attachments/assets/f81fc0c2-9233-48cd-8a9d-2577b1d33d57

Ver en YouTube

Características principales

Indetectable por sistemas anti-bot — Cloudflare, DataDome, PerimeterX, etc.
Gestión inteligente de perfiles — estrategia maestro/instantánea/clon que preserva los inicios de sesión entre sesiones
Filtrado de argumentos stealth — elimina automáticamente más de 30 banderas de Chrome detectables (firmas de Puppeteer/Playwright, marcadores de automatización)
Soporte multi-instancia — inicia y gestiona múltiples navegadores simultáneamente
Un backend compartido entre sesiones — cada sesión de cliente se conecta a un proceso backend compartido en lugar de iniciar el suyo propio, uno por escritorio para que un lanzamiento con ventana aterrice en una pantalla real; el arranque en frío simultáneo está probado a escala con 40 sesiones concurrentes, todas utilizables en segundos contra un solo backend
Auto-sufijo para perfiles ocupados — github-session se convierte automáticamente en github-session-2 cuando está ocupado
Recuperación de huérfanos — limpia de forma segura procesos de navegador filtrados sin matar los activos
Persistencia de sesión — los perfiles clonados heredan cookies, inicios de sesión y datos web del maestro
Cero tiempo de espera por inactividad — los navegadores permanecen activos hasta que se cierran explícitamente
Acceso CDP completo — manipulación del DOM, intercepción de red, ejecución de JavaScript, capturas de pantalla

Inicio rápido

Añade a tu configuración de MCP (claude_desktop_config.json, .claude/settings.json, etc.):

{
  "mcpServers": {
    "stealth-chrome-devtools-mcp": {
      "command": "uvx",
      "args": ["stealth-chrome-devtools-mcp==2.0.6"]
    }
  }
}

O instala vía pip:

pip install stealth-chrome-devtools-mcp==2.0.6

Los fallos se notifican a los mantenedores por defecto, con tu nombre de usuario y nombre de máquina eliminados. Consulta Notificación de errores para ver qué contiene un informe y cómo desactivarlo.

Desarrollo local

{
  "mcpServers": {
    "stealth-chrome-devtools-mcp": {
      "command": "uv",
      "args": [
        "--directory", "/path/to/stealth-chrome-devtools-mcp",
        "run", "stealth-chrome-devtools-mcp"
      ]
    }
  }
}

Cómo funciona

Estrategia de perfil de navegador

C:\stealth-mcp-browser-sessions\
  master/              # Your primary Chrome profile (logins, cookies, extensions)
  master-snapshot/     # Safe copy refreshed while master is closed
  sessions/            # Cloned profiles for concurrent use
    github-session/
    github-session-2/  # Auto-suffixed when github-session is busy

spawn_browser() usa el perfil maestro cuando está disponible
Antes de abrir el maestro, el servidor actualiza master-snapshot
Cuando el maestro está ocupado, se crea un clon a partir de la instantánea
Los clones heredan todas las cookies, inicios de sesión y datos de sesión
Las instantáneas obsoletas se actualizan automáticamente cuando cambian los archivos de autenticación

Los clones excluyen las cachés de Chrome regenerables, por lo que cada uno ocupa unos pocos MB en lugar de varios GB. Los auto-clones desechables se eliminan al cerrar, y un límite de almacenamiento (STEALTH_MCP_CLONE_STORAGE_CAP_GB, 10 GB por defecto) recupera los clones inactivos más antiguos si alguno llegara a filtrarse — de modo que sessions/ se mantiene acotado. La expulsión por límite es recuperable: un clon expulsado se mueve a sessions/.trash/ y solo se purga después de una ventana de retención (STEALTH_MCP_CLONE_TRASH_RETENTION_HOURS, 24 h por defecto), de modo que una expulsión errónea puede restaurarse en lugar de perderse.

Los perfiles con nombre que creas explícitamente (p. ej., github-session) persisten y nunca se eliminan. Pero incluso un perfil "persistente" es ~98% regenerable (cachés más el modelo de IA integrado de Chrome de varios GB). Así que cuando sessions/ supera STEALTH_MCP_BROWSER_SESSION_STORAGE_CAP_GB (20 GB por defecto), los perfiles con nombre inactivos más grandes se recortan de esos directorios regenerables mientras se preserva cada inicio de sesión — Chrome los reconstruye en el siguiente lanzamiento. Los perfiles en uso nunca se tocan.

Nota para máquinas compartidas: la raíz de sesiones del navegador por defecto es C:\stealth-mcp-browser-sessions (raíz de la unidad), que contiene tus cookies de sesión iniciada y datos de sesión. En una máquina de un solo usuario esto es correcto. En un equipo Windows compartido multiusuario, otros usuarios locales podrían leerlo — apunta STEALTH_MCP_BROWSER_SESSION_ROOT a una ubicación dentro de tu perfil de usuario (p. ej., %LOCALAPPDATA%\stealth-mcp) para que las ACL de usuario del sistema operativo lo protejan.

Filtrado de argumentos stealth

El servidor elimina automáticamente las banderas de Chrome que comprometerían el stealth:

Categoría	Ejemplos	Por qué se eliminan
Señales de automatización	`--enable-automation`, `--test-type`	Establece `navigator.webdriver=true`
Fugas de huella digital	`--disable-gpu`, `--disable-webgl`	Detectables mediante sondas WebGL/canvas
Valores por defecto de Puppeteer	`--disable-backgrounding-occluded-windows`	Huella de firma de bot
Valores por defecto de Playwright	`--password-store=basic`, `--use-mock-keychain`	Huella de firma de bot

Los argumentos eliminados se notifican en spawn_diagnostics.stealth_args_stripped.

Recuperación de huérfanos

Al reiniciar el servidor, el sistema de limpieza de procesos:

Recolecta solo los navegadores cuyo backend propietario está muerto — cada navegador rastreado registra qué backend lo inició, de modo que dos backends ejecutándose en paralelo nunca recolectan los navegadores del otro
Mantiene el rastreo de create_time como segunda red de seguridad: nunca mata un proceso que se inició después de que comenzara la sesión actual del servidor
Maneja de forma segura psutil.AccessDenied en procesos elevados de Windows

Navegación con ventana y dónde se abre la ventana

Un navegador con ventana aparece en el escritorio del proceso que lo lanzó, no del que lo solicitó. Dado que las sesiones comparten un backend, un backend que se inició por primera vez desde un inicio de sesión SSH o una sesión de servicio de Windows no puede mostrar una ventana a nadie — incluidas las sesiones que se ejecutan en el escritorio físico.

Por eso el backend se vincula por contexto de pantalla: uno por escritorio, más uno para un contexto sin ventana. El descubrimiento prefiere un backend que pueda mostrar una ventana, lo que significa que un spawn_browser(headless=False) impulsado por SSH usa automáticamente el backend del escritorio y su ventana se abre en la pantalla real. Cuando no existe tal backend, el lanzamiento falla en lugar de devolver un navegador invisible; ejecuta stealth-chrome-devtools doctor para ver qué contextos tienen un backend. Los lanzamientos sin ventana funcionan desde cualquier lugar.

Ejemplos de uso

# Spawn with default master profile
spawn_browser()

# Named session with login persistence
spawn_browser(user_data_dir="github-session")

# Same name while first is open → auto-suffixes to github-session-2
spawn_browser(user_data_dir="github-session")

# Headless with stealth (bad args auto-stripped)
spawn_browser(headless=True, browser_args=["--enable-automation"])
# → stealth_args_stripped: ["--enable-automation stripped: sets navigator.webdriver=true"]

Herramientas MCP

Herramienta	Descripción
`spawn_browser`	Lanza una nueva instancia de navegador stealth
`navigate`	Navega a una URL
`take_screenshot`	Captura una captura de pantalla de la página
`execute_script`	Ejecuta JavaScript en el contexto de la página
`query_elements`	Busca elementos DOM por selector CSS
`click_element`	Hace clic en un elemento
`type_text`	Escribe texto en un campo de entrada
`get_page_content`	Obtiene el contenido HTML de la página
`list_instances`	Lista todas las instancias de navegador activas
`close_instance`	Cierra un navegador específico
`list_network_requests`	Muestra el tráfico de red interceptado
`get_cookies` / `set_cookie`	Gestiona las cookies del navegador

94 herramientas en 11 secciones — el recuento se deriva del registro de herramientas en vivo, nunca se mantiene a mano. Ver el mapa de navegación completo →.

Eso es lo que el servidor ofrece, que no es lo mismo que lo que la puerta de lanzamiento prueba. En el SHA de lanzamiento del registro de evidencia, 3 de esas 94 están cualificadas para lanzamiento: verificadas de extremo a extremo sobre el transporte stdio real que un cliente realmente habla. El resto se ejecutan contra Chrome real mediante la suite E2E pero a través de una costura en proceso, por lo que están served-unqualified en el cable — probadas, no verificadas allí. RELEASE_CONTRACT.md lista el estado de cada herramienta y es la única fuente para esos números.

Pruebas

# Unit tests only (no Chrome needed)
uv run pytest -m "not integration"

# All tests (needs Chrome installed)
uv run pytest

# Verbose with short tracebacks
uv run pytest -v --tb=short

Si tu ruta de checkout contiene espacios o un &, uv run pytest falla con Failed to canonicalize script path — usa el Python del venv directamente: .venv\Scripts\python.exe -m pytest -m "not integration". Consulta CONTRIBUTING.md para el flujo completo de pruebas/puertas.

Una suite integral cubre el filtrado de argumentos stealth, la resolución de perfiles, la recuperación de huérfanos, los barridos de límite de almacenamiento, la CLI de operaciones y la integración completa del navegador.

Variables de entorno

Todas opcionales. Los valores por defecto funcionan para uso normal. Configúralas en tu shell, o en ~/.stealth-mcp/.env — cada clave está documentada en .env.example.

Un .env en tu directorio de proyecto se ignora deliberadamente. El backend es un proceso compartido lanzado con la carpeta que tu cliente MCP tuviera abierta, por lo que leer el .env del proyecto significaba leer la configuración de aplicación de otra persona — lo que provocaba un fallo total del servidor ante un DATABASE_URL ordinario y adoptaba silenciosamente el PORT, DEBUG y SENTRY_DSN de esa aplicación como propios del servidor.

Variable	Valor por defecto	Propósito
`STEALTH_MCP_BROWSER_SESSION_ROOT`	`C:\stealth-mcp-browser-sessions` (Win) / `~/.stealth-mcp-browser-sessions` (Unix)	Carpeta base para perfiles
`BROWSER_MASTER_USER_DATA_DIR`	`<root>/master`	Ruta del perfil maestro de Chrome
`BROWSER_MASTER_SNAPSHOT_DIR`	`<root>/master-snapshot`	Origen de la instantánea para clones
`BROWSER_PROFILE_CLONE_ROOT`	`<root>/sessions`	Carpeta para copias de perfiles
`BROWSER_PROFILE_REFRESH_DAYS`	`7`	Actualizar copias después de N días (`0` = desactivar)
`STEALTH_MCP_CLONE_STORAGE_CAP_GB`	`10`	Límite de almacenamiento total de auto-clones; los clones inactivos más antiguos se recuperan al superarse (`0` = desactivar). Los perfiles con nombre y los clones en uso nunca se tocan.
`STEALTH_MCP_BROWSER_SESSION_STORAGE_CAP_GB`	`20`	Límite de almacenamiento total de `sessions/`; al superarse, los perfiles con nombre inactivos más grandes se recortan de los directorios regenerables de caché/modelo — se conservan los inicios de sesión (`0` = desactivar). (Renombrado desde `STEALTH_MCP_SESSION_STORAGE_CAP_GB`; actualiza tu configuración — el nombre antiguo ya no se lee.)
`STEALTH_MCP_CLONE_TRASH_RETENTION_HOURS`	`24`	Cuánto tiempo permanece recuperable un clon expulsado por límite en `sessions/.trash/` antes de purgarse (`0` = purgar en el siguiente barrido).
`STEALTH_MCP_CLONE_OUTPUT_DIR`	`~/.stealth-mcp/element_clones`	Dónde se escriben las capturas de pantalla, los volcados de respuestas grandes y los archivos de clones de elementos. Se mantiene en un directorio por usuario (nunca dentro del paquete instalado) para que un `site-packages` de solo lectura no rompa las capturas.
`BROWSER_IDLE_TIMEOUT`	`0`	Tiempo de espera de limpieza por inactividad (`0` = desactivado)
`STEALTH_CHROME_PROFILE_KEY`	sin definir	Forzar una clave de clon estable
`STEALTH_MCP_CLIENT_ROOTS_TIMEOUT_SECONDS`	`5`	Plazo para la solicitud `roots/list` que la ruta de auto-clon envía al cliente MCP para nombrar un clon. El `roots` de MCP es opcional, por lo que un cliente puede no responder nunca; al expirar, el nombre del clon se reduce a `CODEX_WORKSPACE`/`CLAUDE_PROJECT_DIR`/`PWD`/cwd (`0` = no preguntar nunca).
`STEALTH_BROWSER_DEBUG`	`false`	Habilitar registro de depuración
`STEALTH_MCP_NO_ERROR_REPORTING`	`false`	Establecer en `true` para desactivar la notificación de errores

CLI

Instala un comando de operaciones stealth-chrome-devtools para gestionar el servidor y su uso de disco. (Esto es para operaciones — para manejar un navegador, usa el servidor MCP o su backend HTTP).

Estos cuatro solo leen y previsualizan — no cambian nada, y la suite de pruebas los ejecuta en cada commit, por lo que se sabe que funcionan:

stealth-chrome-devtools status
stealth-chrome-devtools profiles
stealth-chrome-devtools cleanup
stealth-chrome-devtools cleanup --browser-session-cap-gb 12

status informa si el backend está activo más la raíz de sesiones del navegador y ambos límites; profiles lista los perfiles con tamaño / rol / en uso; cleanup previsualiza el disco recuperable (ejecución en seco), y --browser-session-cap-gb lo previsualiza con un límite más estricto.

Estos no se ejecutan automáticamente — --apply elimina, serve no retorna, y doctor requiere Chrome instalado:

stealth-chrome-devtools cleanup --apply               # actually reclaim
stealth-chrome-devtools doctor                        # check Chrome / environment
stealth-chrome-devtools serve --http --port 19222     # start the server

cleanup elimina los auto-clones inactivos por encima del límite de clones y recorta los perfiles con nombre inactivos hasta su estado de sesión — se conservan los inicios de sesión — por encima del límite de sesiones del navegador. Es una ejecución en seco a menos que pases --apply, nunca toca perfiles en uso, y usa los mismos selectores que el barrido automático, por lo que la vista previa coincide con --apply.

Preparación del perfil maestro

Inicia el servidor MCP
Llama a spawn_browser() sin user_data_dir
Inicia sesión en tus cuentas en el navegador que se abre
Ciérralo — las sesiones futuras usan este perfil o clonan desde él

Requisitos

Python 3.11+
Chrome, Chromium o Microsoft Edge
uv (recomendado) o pip
Una sesión de escritorio para navegación con ventana (sin ventana funciona desde SSH, CI y servicios)

Notificación de errores

Los bloqueos y errores se reportan a Sentry de forma predeterminada, para que un fallo que encuentres sea un fallo que podamos ver y corregir. No hay nada que instalar ni nada que configurar: el SDK viene incluido con el paquete y el destino está integrado.

Qué contiene un reporte. El tipo de excepción y el mensaje, el stack trace, la versión del paquete y la plataforma. Tres cosas quedan fuera:

tu nombre de máquina (el server_name de Sentry) se elimina por completo;
tu nombre de usuario se elimina de todas las rutas, por lo que un frame del stack se lee como C:\Users\~\..., /home/~/... o /Users/~/... en lugar de tu directorio de inicio;
las variables locales no se capturan en absoluto. El SDK de Sentry las envía de forma predeterminada; nosotros lo desactivamos, porque una variable local en esta herramienta puede contener una contraseña de proxy, un encabezado Authorization o Cookie, o un script que le pediste que ejecute — secretos que ninguna regla de ruta podría rescatar.

Eso es universal — se ejecuta en cada instalación, incluida la nuestra, y no hay forma de volver a optar por enviar esos campos. Lo que deliberadamente deja intacto es la parte que hace útil un reporte: el tipo de error, la ruta del módulo después del segmento de inicio, la línea de código que falló y la versión de la que proviene.

Un mensaje de error aún cita aquello con lo que la llamada que falló estaba trabajando — una URL a la que navegaste, un archivo que solicitaste. Si ese no es un intercambio que quieras hacer, desactiva el reporte.

Para desactivarlo, establece una variable en tu shell o en ~/.stealth-mcp/.env:

STEALTH_MCP_NO_ERROR_REPORTING=true

Las versiones anteriores leían SENTRY_DSN del entorno. Ya no lo hacen — esa variable pertenece a tu aplicación, y un backend compartido lanzado desde tu carpeta de proyecto la estaba captando. Consulta Environment Variables para saber por qué esta herramienta ignora por completo el .env de tu proyecto.

Configuración de desarrollo

git clone https://github.com/DevinoSolutions/stealth-chrome-devtools-mcp
cd stealth-chrome-devtools-mcp
uv sync --extra dev --extra test   # install linters + test deps
npm install                        # arm husky pre-commit/pre-push hooks

Las seis puertas de calidad se ejecutan automáticamente en cada commit: ruff format, ruff check, ty check, vulture, suppression-owner check, file-budget check. Las pruebas unitarias se ejecutan antes del push.

Documentación

CLAUDE.md — mapa de navegación del árbol de código fuente + glosario + convenciones
DESIGN.md — invariantes de arquitectura y el porqué detrás de ellas
RUNBOOK.md — operación del backend: verbos, registros, recuperación, ruta de verificación MCP
CONTRIBUTING.md — clone → install → test, la puerta de calidad, convenciones

Licencia

Consulta LICENSE.

Creado por Devino Solutions