browser-mcp-automation 1.0.0

Browser automation MCP server with triple engine (static + selenium + playwright)

BrowserMCP — Browser Automation MCP Server

Servidor MCP para automatización de navegador web. Navega, extrae contenido, hace clic, rellena formularios, toma capturas de pantalla y más. Arquitectura de triple motor: Selenium (Chromium), Playwright (Chromium) y motor estático (BeautifulSoup) como fallback.

Features / Funcionalidades

Tool / Herramienta	Description / Descripción
navigate	Navega a una URL y devuelve título, URL y texto
extract	Extrae texto de elementos CSS selector
click	Hace clic en un elemento por selector CSS
click_by_text	Hace clic en un botón/enlace por su texto visible (soporta múltiples textos con |)
fill	Rellena un campo de formulario con un valor
run_script	Ejecuta JavaScript en el navegador y devuelve el resultado
screenshot	Toma captura de pantalla (base64 PNG)
forms	Lista formularios con campos, labels y tipos
links	Lista todos los enlaces (internos/externos)
scroll	Desplaza la página (down/up/bottom/top)
wait	Espera una cantidad de milisegundos
engine_info	Muestra el motor activo (selenium/playwright/static)

Tech Stack

• Python — >=3.11
• Framework: mcp (FastMCP) via stdio JSON-RPC
• Selenium Engine: selenium + Chromium (headless)
• Playwright Engine: playwright + Chromium (experimental)
• Static Engine: requests + beautifulsoup4 + lxml (fallback)

Selenium Setup / Configuración

El servidor usa Chromium via Selenium en modo headless. Auto-detecta el binario de Chromium.

# Instalar dependencias
pip install mcp selenium beautifulsoup4 lxml requests httpx

# Ejecutar servidor
python server.py

# Forzar motor específico
export BROWSER_ENGINE=selenium    # Usar Selenium
export BROWSER_ENGINE=playwright  # Usar Playwright (experimental)
export BROWSER_ENGINE=static      # Usar motor estático (sin navegador)
export BROWSER_ENGINE=auto        # Intentar Selenium, fallback a static (por defecto)

Chromium en Ubuntu

El servidor busca chromium-browser, chromium y la ruta de snap. Si no encuentra Chromium, usar --headless=new.

Triple Engine Architecture

• Selenium (preferred): navegador real — soporta click, fill, screenshot, scroll, JS execution
• Playwright (experimental): navegador real alternativo — soporta mismas capacidades que Selenium
• Static (fallback): solo extracción HTML — no soporta interacciones dinámicas
• Auto (default): intenta Selenium, fallback automático a estático

🔧 Recent Improvements

• click_by_text Tool — Click buttons, links, or interactive elements by visible text content. Supports multiple texts separated by | (e.g. Postularme|Apply|Aplicar). Uses JavaScript execution to find elements by text, not CSS selectors.
• run_script Tool — Execute arbitrary JavaScript in the browser and return the result. Useful for debugging, inspecting page state, and complex interactions.
• Improved Label Detection — get_forms() now also finds labels in <div for="..."> elements (not just <label for="...">), with JS-based fallback for React SPAs.
• Multiple Submit Fix — click_by_text avoids clicking the wrong submit button by matching text content ("Responder", "Enviar", etc.) instead of CSS selector.
• Headless Mode — Chrome now runs with --headless=new (no visible windows)
• Random Debug Port — --remote-debugging-port=0 + --remote-debugging-address=127.0.0.1 (security: no more fixed port 9222 exposed)
• Temp Dir Cleanup — Chrome temp directories are cleaned on server shutdown (no disk leaks)
• XPath Injection Fix — Label lookup escapes special characters in form IDs
• Configurable Settings — CHROME_WINDOW_SIZE, CHROME_LANG, BROWSER_TEXT_MAX, BROWSER_JS_FILL_THRESHOLD env vars
• Playwright Scroll Fix — "bottom" now scrolls to scrollHeight instead of fixed 10000px
• Playwright Async Fix — _sync_run uses new_event_loop() (no more nested event loop deadlocks)
• Scroll Case-Insensitive — DOWN/down/Down all work
• Double Truncation Removed — Server no longer applies a second text truncation after the engine
• Client Uses sys.executable — No more hardcoded .venv/bin/python path
• Selenium in CLI — --engine selenium now available in the test client
• Dead Dependencies Removed — httpx and websocket-client cleaned from pyproject.toml

Project Structure

browser-mcp/
├── server.py                 # MCP server entry point (tools)
├── engines/
│   ├── __init__.py
│   ├── base.py               # BaseEngine, PageResult, LinkInfo, FormInfo
│   ├── selenium_engine.py    # Selenium/Chromium engine
│   ├── static.py             # Static HTML engine (requests + BS4)
│   └── playwright_engine.py  # Playwright engine (experimental)
├── client.py                 # Test client CLI
└── pyproject.toml