MCP Browser Use

Qué puedes lograr con este MCP

Este proyecto tiene como objetivo capacitar a los agentes de IA para realizar navegación web, automatización de navegadores, scraping y automatización con el Protocolo de Contexto de Modelo (MCP) y Selenium.

La característica especial de este MCP es que puede manejar múltiples agentes accediendo a múltiples ventanas del navegador. No es necesario iniciar múltiples imágenes de Docker, máquinas virtuales o computadoras para tener múltiples agentes de scraping. Y aún se puede usar un solo perfil de navegador en todos los agentes. Cada agente tendrá sus propias ventanas y no interferirán entre sí.

¡Esto hace que el manejo de múltiples agentes sea fluido: simplemente inicia tantos agentes como quieras y funcionará! Usa dos instancias de Claude Code, una instancia de Codex CLI, una instancia de Gemini CLI y una instancia de fast-agent, todo en una sola computadora, usando el mismo perfil de navegador y trabajando (más o menos) en paralelo.

Nuestra misión es permitir que los agentes de IA completen cualquier tarea web con una supervisión humana mínima, todo basado en instrucciones en lenguaje natural.

Related MCP server: Selenium MCP Server

Aspectos destacados de las funciones

• Truncamiento de HTML: El MCP te permite configurar el truncamiento de las páginas HTML. Otros MCP de scraping pueden abrumar a la IA con instantáneas de accesibilidad o volcados HTML que son más grandes que la ventana de contexto. Este MCP te ayudará a gestionar el tamaño máximo de página configurando la variable de entorno MCP_MAX_SNAPSHOT_CHARS.

• Múltiples ventanas de navegador y múltiples agentes: Puedes conectar múltiples agentes a este MCP de forma independiente, sin necesidad de coordinación por parte de los agentes. Cada agente puede trabajar con el mismo perfil de navegador, lo cual es útil cuando los inicios de sesión deben persistir entre agentes. Cada agente obtiene su propia ventana de navegador, por lo que no interfieren entre sí. Utiliza el TargetId del Protocolo de DevTools de Chrome para identificar las ventanas del navegador.

Limitaciones conocidas

• Contexto de Iframe: Las interacciones de varios pasos dentro de iframes requieren especificar iframe_selector para cada acción. El contexto del navegador se restablece después de cada llamada a la herramienta por motivos de fiabilidad. Para flujos de trabajo con iframes, repite el parámetro del selector de iframe en cada llamada a click_element, fill_text o debug_element.

Configuración / Instalación

1. Clonar y crear un entorno virtual

git clone https://github.com/janspoerer/mcp_browser_use.git
cd mcp_browser_use
python3 -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install -r requirements.txt

2. Instalar Chrome Beta

Recomendamos usar Chrome Beta (no tu Chrome habitual) para que los agentes de IA puedan ejecutarse con depuración remota sin interferir con tu navegación diaria.

macOS:

brew install --cask google-chrome-beta

Ubuntu / Debian:

wget -q -O - https://dl.google.com/linux/linux_signing_key.pub | sudo apt-key add -
echo "deb [arch=amd64] http://dl.google.com/linux/chrome/deb/ stable main" \
    | sudo tee /etc/apt/sources.list.d/google-chrome.list
sudo apt update && sudo apt install -y google-chrome-beta

Windows: Descarga e instala Chrome Beta desde google.com/chrome/beta.

Después de instalar, verifica:

google-chrome-beta --version      # Linux
# or
"/Applications/Google Chrome Beta.app/Contents/MacOS/Google Chrome Beta" --version  # macOS

Servidores Linux headless — Xvfb (pantalla virtual)

Chrome necesita una pantalla. En servidores Linux headless (sin interfaz gráfica), usa Xvfb:

sudo apt install -y xvfb

# Start a virtual display on screen :99
Xvfb :99 -screen 0 1920x1080x24 &

# Tell Chrome which display to use
export DISPLAY=:99

Agrega export DISPLAY=:99 a tu .bashrc o .profile para hacerlo permanente.

3. Configurar e iniciar

• Después de instalar Chrome Beta, apunta al ejecutable de Chrome Beta en tu .mcp.json como se describe en la sección de Configuración de variables de entorno a continuación.

• Inicia el servidor MCP (si no sabes cómo hacerlo, consulta la sección "Cómo usar (este) MCP" a continuación).

Cómo usar (este) MCP

Consulta la documentación de MCP en modelcontextprotocol.io.

Ten en cuenta que deberás instalar todas las dependencias en el entorno de Python al que apunta tu archivo de configuración de MCP. Por ejemplo, si apuntas al ejecutable python o python3, apuntarás al entorno global de Python. Por lo general, es preferible apuntar a un entorno virtual como:

/Users/yourname/code/mcp_browser_use/.venv/bin/python

Si has clonado este repositorio en tu carpeta local code, tu archivo de configuración de MCP debería verse así:

{
    "mcpServers": {
        "mcp_browser_use": {
            "command": "/Users/janspoerer/code/mcp_browser_use/.venv/bin/python",
            "args": [
                "/Users/janspoerer/code/mcp_browser_use/mcp_browser_use"
            ]
        }
    }
}

y estará aquí (en macOS): /Users/janspoerer/Library/Application Support/Claude/claude_desktop_config.json.

Consulta el archivo requirements.txt para ver qué dependencias necesitas instalar.

Reinicia Claude para ver si la configuración JSON es válida. Claude te llevará a los registros de errores del MCP si algo no está bien.

Si la configuración fue exitosa, verás un pequeño icono de martillo en la parte inferior derecha de la ventana "New Chat" en Claude. Junto al martillo estará el número de funciones que proporciona el MCP.

Haz clic en el martillo para ver las herramientas disponibles.

Configuración de variables de entorno

IMPORTANTE: Define todas las variables de entorno en tu archivo .mcp.json de la raíz del proyecto, NO en archivos .env. Esto garantiza una única fuente de verdad sin conflictos.

Configuración recomendada (Chrome Beta)

Agrega variables de entorno a la sección env de tu archivo .mcp.json:

{
  "mcpServers": {
    "mcp_browser_use": {
      "type": "stdio",
      "command": "/path/to/.venv/bin/python",
      "args": ["-m", "mcp_browser_use"],
      "env": {
        "BETA_PROFILE_NAME": "SeleniumProfile",
        "BETA_EXECUTABLE_PATH": "/Applications/Google Chrome Beta.app/Contents/MacOS/Google Chrome Beta",
        "BETA_PROFILE_USER_DATA_DIR": "/Users/yourname/Library/Application Support/Google/Chrome Beta",
        "CHROME_REMOTE_DEBUG_PORT": "9225",
        "MCP_HEADLESS": "0",
        "MCP_ENABLE_EXTENSIONS": "1",
        "MAX_SNAPSHOT_CHARS": "10000"
      }
    }
  }
}

Ejemplo para Windows:

"env": {
  "BETA_PROFILE_NAME": "SeleniumProfile",
  "BETA_EXECUTABLE_PATH": "C:\\Program Files\\Google\\Chrome Beta\\Application\\chrome.exe",
  "BETA_PROFILE_USER_DATA_DIR": "C:\\Users\\yourname\\AppData\\Local\\Google\\Chrome Beta\\User Data",
  "CHROME_REMOTE_DEBUG_PORT": "9225",
  "MCP_HEADLESS": "0",
  "MCP_ENABLE_EXTENSIONS": "1"
}

Referencia de variables de entorno

¿Por qué usar Chrome Beta?

Usar Chrome Beta (o Canary) evita conflictos con tu navegador Chrome habitual:

• Los agentes de IA requieren que Chrome se ejecute con la depuración remota habilitada

• Tu instancia normal de Chrome no puede ejecutarse con depuración remota

• Chrome Beta permite que ambos coexistan en el mismo sistema

Recomendaciones de perfil

• Usa un perfil dedicado como "SeleniumProfile" (NO "Default")

• Esto evita conflictos si abres Chrome Beta manualmente

• Las extensiones y los inicios de sesión persisten en este perfil entre sesiones

• Cada agente de IA obtiene su propia ventana de navegador pero comparte el perfil

Herramientas disponibles

Depuración

Comprueba si el navegador se está ejecutando visitando esta URL en tu navegador principal (no en el navegador automatizado):

http://127.0.0.1:9223/json/version

Mostrará algo como esto si el navegador se está ejecutando:

{
   "Browser": "Chrome/140.0.7339.24",
   "Protocol-Version": "1.3",
   "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/140.0.0.0 Safari/537.36",
   "V8-Version": "14.0.365.3",
   "WebKit-Version": "537.36 (@f8765868e23d9ee5209061fc999f6495c525cd13)",
   "webSocketDebuggerUrl": "ws://127.0.0.1:9223/devtools/browser/d8f511eb-947c-4eb1-833d-917212a92394"
}

Archivos de bloqueo y coordinación

Este MCP utiliza bloqueos basados en archivos para coordinar múltiples agentes que acceden al mismo perfil de navegador. Todos los archivos de bloqueo se almacenan en tmp/mcp_locks/ en el directorio raíz del proyecto para una fácil inspección.

Tipos de archivos de bloqueo

Bloqueo de acción (<hash>.softlock.json y <hash>.softlock.mutex)

• Asegura que solo un agente pueda realizar acciones en el navegador a la vez

• TTL predeterminado: 30 segundos (configurable mediante MCP_ACTION_LOCK_TTL)

• Se renueva automáticamente con un latido mientras el agente está trabajando

• Los agentes esperan hasta 60 segundos para adquirir el bloqueo (configurable mediante MCP_ACTION_LOCK_WAIT)

Registro de ventanas (<hash>.window_registry.json)

• Rastrea qué agente posee qué ventana del navegador

• Contiene: targetId, windowId, PID del proceso, marca de tiempo del último latido

• Se utiliza para la limpieza de huérfanos: cierra automáticamente las ventanas de agentes bloqueados/obsoletos

• Umbral de obsolescencia: 5 minutos (configurable mediante MCP_WINDOW_REGISTRY_STALE_SECS)

Mutex de inicio (<hash>.startup.mutex)

• Asegura el inicio de una sola instancia de navegador por perfil

• Se utiliza durante la coordinación inicial del lanzamiento del proceso de Chrome

Formato de archivo: El <hash> es un hash SHA-256 derivado del user_data_dir y profile_name de tu perfil de Chrome, lo que garantiza una identificación estable entre procesos.

Configuración

Puedes personalizar el comportamiento de bloqueo con estas variables de entorno:

# Lock directory (default: <project_root>/tmp/mcp_locks/)
MCP_BROWSER_LOCK_DIR=/path/to/locks

# Action lock TTL in seconds (default: 30)
MCP_ACTION_LOCK_TTL=30

# Max wait time for action lock in seconds (default: 60)
MCP_ACTION_LOCK_WAIT=60

# Window registry stale threshold in seconds (default: 300)
MCP_WINDOW_REGISTRY_STALE_SECS=300

# File mutex stale threshold in seconds (default: 60)
MCP_FILE_MUTEX_STALE_SECS=60

Limpieza de ventanas huérfanas

Cuando un agente inicia una sesión de navegador, automáticamente:

1. Comprueba el registro de ventanas en busca de entradas de procesos muertos (el PID ya no existe)

2. Comprueba si hay entradas obsoletas (sin latido durante >5 minutos)

3. Cierra las ventanas huérfanas a través del Protocolo de DevTools de Chrome

4. Limpia las entradas del registro

Esto asegura que los agentes bloqueados o terminados no dejen ventanas de navegador zombis abiertas.

Video de demostración (YouTube)

Ejecutar pruebas

NO queremos usar pytest-asyncio.

pip install -e ".[test]"`