MCP client (Claude Code, Claude Desktop, Cursor, …)
                          │
                          │  JSON-RPC over stdio
                          ▼
              ┌───────────────────────────┐
              │   stealth-browser-mcp     │
              │   16 tools, one browser   │
              └─────┬───────────────┬─────┘
                    │               │
     credentials    │               │   CDP + Puppeteer
                    ▼               ▼
        ┌───────────────────┐   ┌───────────────────────┐
        │  macOS Keychain   │   │  Google Chrome        │
        │  stealth-mcp:*    │   │  + stealth plugin     │
        │  passwords,       │   │  + WebAuthn virtual   │
        │  passkey material │   │    authenticator      │
        └───────────────────┘   └───────────┬───────────┘
                                            │
                                            ▼
                              ┌─────────────────────────┐
                              │  Persistent profile dir │
                              │  cookies · localStorage │
                              │  IndexedDB · sessions   │
                              └─────────────────────────┘

git clone https://github.com/lauyuen/stealth-browser-mcp.git
cd stealth-browser-mcp
npm install

cp .env.example .env

npm run check-stealth

claude mcp add stealth-browser -- node /absolute/path/to/stealth-browser-mcp/src/server.js

{
  "mcpServers": {
    "stealth-browser": {
      "command": "node",
      "args": ["/absolute/path/to/stealth-browser-mcp/src/server.js"]
    }
  }
}

{
  "mcpServers": {
    "stealth-browser": {
      "command": "node",
      "args": ["/absolute/path/to/stealth-browser-mcp/src/server.js"],
      "env": {
        "BROWSER_PROFILE_DIR": "/absolute/path/to/a/private/profile/dir"
      }
    }
  }
}

npm run login -- https://example.com

npm run keychain set github you@example.com     # prompts; input is not echoed
npm run keychain get github you@example.com     # confirms presence, prints length only
npm run keychain delete github you@example.com

GXP10

`service` es una etiqueta arbitraria que eliges tú — solo tiene que coincidir entre la CLI y la llamada a la herramienta.

También puedes pasar la contraseña como argumento final de CLI para la escritión de scripts, pero quedará en el historial de tu shell y en la lista de procesos, por lo que el comando te avisa cuando lo haces.

## Passkeys

Chrome expone un [WebAuthn virtual del que habla el Protocolo DevTools](https://chromedevtools.github.io/devtools-protocol/tot/WebAuthn/) — un autenticador de software pensado para probar flujos WebAuthn. Este servidor lo maneja y conserva el material de claves resultante en el Keychain para que supere el ciclo de la terapia.

**Registrar una passkey de automatización**

1. Llama a `passkey_enable_virtual_authenticator` sin argumentos.
2. Navega al flujo del sitio para “añadir una passkey” y complétalo. El autenticador virtual responde al desafío; no aparece ninguna solicitud del sistema.
3. Llama a `passkey_save_registration` con `rpId` del sitio y tu cuenta.

**Usarla más tarde**

Llama a `passkey_enable_virtual_authenticator` con `rpId` y `account` para inyectar la credencial antes de navegar, y el sitio te autenticará sin muestra ninguna pregunta.

> \[!CAUTION]
> Una passkey retenida de esta forma es un archivo, no una clave física. Puede copiarse, que es exactamente lo que las passkeys reales tratan de evitar. Registra con este método solo passkeys de automatización. No lo uses con la passkey que protege tu correo, tu banco o cualquier otra cosa cuya pérdida te importaría.

## Configuración

Toda la configuración se hace mediante variables de entorno, la extensión del proceso o de un archivo `.env`. Consulta [.env.example](.env.example).

| Qué la controla            | Valor por defecto                      | Propósito                                                                       |
|--------------------------- | -------------------------------------- | --------------------------------------------------------------------------------- |
| `BROWSER_PROFILE_DIR`      | `~/.config/stealth-browser-mcp/profile` | Perfil persistente de Chrome. Contiene sesiones reales — mantenlo privado y fuera del control de versiones. |
| `CHROME_EXECUTABLE_PATH`   | Valor por defecto de la plataforma       | Binario de Chrome a controlar. Si la ruta no existe, intentará con Chromium de Puppete. |
| `NAV_TIMEOUT`              | `45000`                                 | Tiempo de espera de navegación y selección, en milisegundos. |

Los indicadores de lanzamiento de Chrome y la ventana gráfica predeterminada de 1280×800 están en [`src/config.js`](src/config.js). Varios de esos indicadores intercambian seguridad por compatibilidad; [SECURITY.md](SECURITY.md#known-weakenings) explica cuáles y por qué deberías eliminar algunos.

## Verificar el sigilo

GXP11

Informa de `navigator.webdriver`, `window.chrome`, `window.chrome.runtime`, el número de plugins, `navigator.languages` y el user agent efectivo, y luego imprime el perfil resuelto y las rutas de Chrome.

Para una comprobación más exigente, apunta el navegador a una página de fingerprinting — por ejemplo `bot.sannysoft.com` o `abrahamjuliot.github.io/creepjs` — con `browser_navigate` seguido de `browser_screenshot`.

Ninguna configuración de stealth es indetectable. Los sitios bien defendidos combinan el fingerprinting con análisis de comportamiento, reputación de IP e historial de cuenta, y seguirán detectando la automatización. Trátalo como «no activa las comprobaciones obvias», no como invisibilidad.

## Solución de problemas

**«Failed to launch the browser process» / perfil bloqueado.** Chrome permite un proceso por directorio de perfil. Cierra cualquier Chrome que hayas iniciado manualmente contra el mismo directorio. El servidor elimina los archivos de bloqueo `Singleton*` obsoletos al iniciarse y se reconectará a una instancia activa a través de su puerto DevTools, pero un Chrome en ejecución que sea el propietario del perfil gana.

**Un sitio cierra la sesión del modelo o lo bloquea.** La sesión almacenada ha caducado. Vuelve a ejecutar `npm run login -- <url>`.

**Los selectores no coinciden.** Llama a `browser_extract_html` con un selector concreto y deja que el modelo lea el marcado real en lugar de adivinar. Las aplicaciones de una sola página suelen montar los inputs tarde — usa `browser_wait_for` primero.

**Aparece un CAPTCHA.** Llama a `browser_open_interactive_window`, resuélvelo tú mismo y continúa. El estado resuelto persiste en el perfil.

**Errores de Keychain en Linux o Windows.** Es de esperar — esa capa es solo de macOS. Las herramientas de navegador funcionan en todas partes; las de credenciales y passkeys no.

## Uso responsable

Este proyecto existe para permitir que un asistente actúe en sitios *en los que ya tienes una cuenta*, usando sesiones *que tú mismo has establecido*. Ese es el alcance previsto, y el diseño de perfil persistente lo refleja.

La automatización de anti-detección y credenciales obviamente puede dirigirse a otros fines. Antes de ejecutarla contra un sitio, ten en cuenta:

* **Los términos de servicio del sitio.** Muchos prohíben el acceso automatizado por completo. Evadir una defensa contra bots puede incumplir un contrato que aceptaste y, en algunas jurisdicciones, el acceso no autorizado conlleva responsabilidad penal. Poder eludir un control no es un permiso para hacerlo.
* **Consentimiento.** Automatiza cuentas que te pertenezcan, o sobre las que tengas autorización por escrito para actuar. Las credenciales de otra persona en tu Keychain no son consentimiento.
* **Carga.** Limita tu propia frecuencia de peticiones. Respeta `robots.txt` cuando corresponda. La automatización que le cuesta dinero real a un sitio es una buena forma de conseguir que la técnica se prohíba para todos.
* **Datos de otras personas.** Las páginas que lee el modelo fluyen hacia el proveedor de tu cliente MCP. No canalices información personal de terceros a través de él.

Las contribuciones que existan principalmente para derrotar las protecciones de un sitio específico, recolectar credenciales o ampliar el abuso no se fusionarán.

## Licencia

[MIT](LICENSE) © Yuen Lau