blowsh-mcp

Servidor de Protocolo de Contexto Modelo para navegación de terminal compatible con JS mediante Browsh

¿Qué es blowsh-mcp?

blowsh-mcp es un servidor de Protocolo de Contexto Modelo (MCP) que expone el poder de Browsh —un navegador de terminal totalmente compatible con JavaScript— a cualquier agente de IA, agente de IDE o cliente MCP. Este proyecto permite que tu IA obtenga y renderice cualquier página web moderna, incluidas las que requieren JavaScript, y reciba el resultado como texto plano, HTML o Markdown fácilmente analizable.

Mnemotécnica: “blowsh” = servidor MCP impulsado por Browsh.

Related MCP server: openmcp

Características principales

• Herramienta fetch_web: herramienta unificada para extraer texto plano legible, HTML o Markdown (tras el renderizado completo de JS). Admite extracción por selector CSS, límites de salida con max_chars y sondeo de estabilización de JS con wait_ms.

• Herramienta search_web: descubre páginas mediante un motor de búsqueda renderizado (DuckDuckGo HTML con respaldo de Bing): resultados clasificados con URLs y fragmentos.

• Herramienta extract_links: lista los hipervínculos (texto + URL absoluta) de cualquier página renderizada con JS para seguimiento de navegación.

• Herramienta fetch_web_batch: obtiene hasta 10 URLs en una sola llamada con aislamiento de errores por URL.

• Protección SSRF: rechaza solicitudes a direcciones de bucle local, privadas, link-local o reservadas (resueltas por DNS), protegiendo el navegador del lado del servidor.

• Documentación de herramientas optimizada para IA: entradas, salidas y casos de uso ilustrados diseñados para una automatización fluida por parte del agente. Las herramientas lanzan errores estructurados con códigos de estado HTTP (isError en respuestas MCP).

• Gestión robusta de Browsh: lanza Browsh una vez, lo mantiene en ejecución, reutiliza un singleton ligero en RAM/CPU y se apaga correctamente al salir.

• Caché de renderizado en memoria con TTL: las obtenciones repetidas se sirven al instante sin volver a renderizar.

• Diseñado para PaaS, Cloud, herramientas de IA locales y agentes de IDE.

Enlaces

• Browsh CLI Browser — El motor de renderizado.

• Firefox — Requerido como backend de Browsh.

• Model Context Protocol (MCP) Specification — El protocolo agente/servidor.

Cómo funciona

1. La IA/el agente realiza una solicitud MCP: fetch_web (URL única), search_web (consulta), extract_links (URL) o fetch_web_batch (hasta 10 URLs).

2. blowsh-mcp lanza Browsh en modo servidor HTTP (en el primer uso) y lo reutiliza para todas las llamadas posteriores.

3. blowsh-mcp solicita la salida sin procesar a Browsh, usando X-Browsh-Raw-Mode: PLAIN (para texto), DOM (para HTML), u obtiene HTML y luego lo convierte a Markdown.

4. La página (tras la ejecución completa de JS) se devuelve como texto plano de terminal, DOM HTML enriquecido o Markdown limpio: la IA/el agente elige el tipo de salida según el procesamiento posterior.

5. Los resultados se guardan en caché en memoria (TTL), por lo que las obtenciones repetidas son instantáneas; cada solicitud se verifica contra SSRF antes de llegar al navegador.

Inicio rápido (Docker — imagen precompilada)

La imagen se publica en GitHub Container Registry y se reconstruye automáticamente en cada push a main mediante GitHub Actions — no se necesita Firefox/Browsh/html2markdown en el host:

docker pull ghcr.io/mokhtarabadi/blowsh-mcp:latest
docker run --rm -i ghcr.io/mokhtarabadi/blowsh-mcp:latest

La bandera -i es obligatoria: el servidor MCP habla JSON-RPC a través de stdin/stdout. Manténla interactiva y canaliza las solicitudes, o apunta tu cliente MCP a ella (consulta Configuración de cliente IA más abajo).

Ejemplo de uso

Desde Claude, Cursor o cualquier agente compatible con MCP:

{
  "tool": "search_web",
  "params": { "query": "bitcoin price today", "max_results": 5 }
}
// → Ranked results with URLs + snippets → feed top URL to fetch_web

{
  "tool": "fetch_web",
  "params": { "url": "https://coindesk.com/price/bitcoin/", "type": "plain" }
}
// → Returns readable plain text (live price as text table, etc)

{
  "tool": "fetch_web",
  "params": { "url": "https://coindesk.com/price/bitcoin/", "type": "markdown", "selector": "main", "wait_ms": 3000 }
}
// → Markdown of <main> only, after JS settles ("# Bitcoin Price\n\n| Time | Price | ...")

{
  "tool": "extract_links",
  "params": { "url": "https://example.com", "limit": 20 }
}
// → [{"text": "Learn more", "url": "https://iana.org/domains/example"}, ...]

{
  "tool": "fetch_web_batch",
  "params": { "urls": ["https://a.com", "https://b.com"], "type": "markdown" }
}
// → Per-URL results; a failing page never fails the batch

La IA recibe:

• Con type: plain: texto legible puro (tablas, listas, contenido principal; ideal para NLP/resúmenes o ingesta de contexto de terminal).

• Con type: html: el marcado HTML completo, después de todo el JavaScript. Úsalo para analizar elementos, construir grafos de enlaces, scraping complejo, etc.

• Con type: markdown: una versión limpia en Markdown, ideal para fragmentos de contexto de LLM, pipelines semánticos y consumos/flujos de trabajo compatibles con IA.

• Los errores están estructurados: las respuestas MCP establecen isError: true con un mensaje FetchError que incluye el estado HTTP cuando está disponible.

Estructura del proyecto

• src/server.ts — servidor MCP que expone herramientas.

• src/browshManager.ts — lanza, supervisa y apaga Browsh.

• src/tools/fetchWeb.ts — implementación de la herramienta fetchWeb (plain, html, markdown; selector/max_chars/wait_ms).

• src/tools/searchWeb.ts — search_web (parser de DuckDuckGo HTML + respaldo de Bing).

• src/tools/extractLinks.ts — extract_links (hipervínculos del DOM renderizado).

• src/tools/fetchWebBatch.ts — fetch_web_batch (multi-URL, aislamiento de errores por URL).

• src/tools/html2markdownManager.ts — envoltorio para el CLI de html2markdown.

• src/ssrf.ts — protección SSRF (bloquea destinos privados/de bucle local/reservados).

• src/cache.ts — caché de renderizado en memoria con TTL.

• src/extract.ts — extracción de contenido principal, ayudantes de selector, truncamiento.

• src/errors.ts — FetchError + formato de mensaje.

• README.md — este archivo.

• Dockerfile — contenedor multi-etapa (compila TS, incluye Firefox, Browsh, html2markdown).

• .github/workflows/docker-publish.yml — CI/CD: compila y publica la imagen en ghcr.io en main/v*.

• .env — anulaciones de configuración. Consulta .env.example para todas las opciones.

Instalación

Requisitos:

• Node.js >= 20.18

• Firefox instalado y en PATH

• Browsh CLI instalado y en PATH

• html2markdown CLI instalado y en PATH

  • En Debian/Ubuntu, instálalo con:

    wget -O /tmp/html2markdown.deb "https://github.com/JohannesKaufmann/html-to-markdown/releases/download/v2.5.2/html2markdown_2.5.2_linux_amd64.deb"
    sudo apt-get install -y /tmp/html2markdown.deb
    rm /tmp/html2markdown.deb

  • O usa el binario precompilado para tu sistema operativo desde la página de lanzamientos.

¿Prefieres Docker? Omite por completo las instalaciones en el host: la imagen multi-etapa incluye Firefox, Browsh y html2markdown. El camino más rápido es la imagen publicada (ghcr.io/mokhtarabadi/blowsh-mcp:latest, consulta Inicio rápido); para compilarla tú mismo:

docker build -t blowsh-mcp:latest .
docker run --rm -i blowsh-mcp:latest

git clone https://github.com/mokhtarabadi/blowsh-mcp.git
cd blowsh-mcp
npm install
npm run build

Ejecutar el servidor MCP

Después de compilar, inicia el servidor con:

node dist/server.js

Reemplaza dist/server.js con la ruta correcta si el resultado de tu compilación difiere.

Crea un archivo .env según sea necesario para la configuración. Por ejemplo:

MCP_TRANSPORT=stdio
BROWSH_FIREFOX_PATH=/usr/bin/firefox-esr
HTML2MARKDOWN_PATH=html2markdown
CACHE_TTL_MS=300000
BROWSH_REQUEST_TIMEOUT_MS=30000
ALLOW_PRIVATE_URLS=false
NODE_ENV=production

• BROWSH_FIREFOX_PATH te permite personalizar el ejecutable de Firefox que usa Browsh durante la operación headless/HTTP.

• HTML2MARKDOWN_PATH te permite especificar una ruta personalizada al binario html2markdown (por defecto: html2markdown en PATH).

• CACHE_TTL_MS, BROWSH_REQUEST_TIMEOUT_MS y ALLOW_PRIVATE_URLS ajustan respectivamente la caché de renderizado, el tiempo de espera por solicitud y la protección SSRF.

• El puerto/host HTTP de Browsh NO es configurable.

Documentación del proyecto

Este README es el punto de entrada orientado al usuario; las reglas orientadas al agente están en AGENTS.md y son de lectura obligatoria antes de cualquier implementación.

API de herramientas

Valores devueltos

• type: plain: texto legible, ejecutado con JS, estilo terminal (o cadena de error).

• type: html: cadena de marcado HTML posterior a JS (o cadena de error). Con selector, solo el HTML del elemento coincidente.

• type: markdown: conversión a Markdown del contenido principal o del elemento seleccionado (o cadena de error). Se conservan enlaces, encabezados, listas y la estructura de la página para un contexto compatible con IA.

• type: pdf: texto plano extraído del documento PDF (mediante pdftotext, límite de 20 MB).

• Los errores están estructurados: una respuesta MCP con isError: true y un mensaje FetchError que incluye el estado HTTP cuando es posible conocerlo (nunca una cadena vacía silenciosa).

Variables de entorno

Configúralas mediante .env (se carga automáticamente) o el entorno:

Selección de herramientas guiada por IA

• Comience con search_web: Para descubrir páginas, ejecute una consulta y elija las mejores URL de resultados; luego obténgalas.

• Use fetch_web para páginas individuales: plain cuando necesite una salida legible rápida para resumir/clasificar; html para analizar elementos, enlaces o tablas; markdown para fragmentos de contexto aptos para LLM. Añada selector/max_chars/wait_ms para mantener la eficiencia de tokens y obtener contenido estable y relevante.

• Use extract_links antes de rastreos profundos: Siga la navegación de forma económica en lugar de obtener DOM completos.

• Use fetch_web_batch para múltiples fuentes: Una sola llamada en lugar de N idas y vueltas; los fallos se aíslan por URL.

Manejo de errores: Las herramientas lanzan FetchError y MCP devuelve isError: true con un mensaje procesable: los protocolos no válidos, los bloqueos de SSRF, los selectores sin coincidencias, los códigos de estado HTTP y los fallos de renderizado nunca son silenciosos.

Protocolo MCP: Configuración del cliente de IA

Antes de configurar su cliente de IA (Claude, Cursor, etc.), debe

1. Instale las dependencias:    npm install

2. Compile el proyecto:    npm run build

3. Inicie el servidor MCP desde la salida compilada:    node dist/server.js

Ejemplo de configuración para Claude Desktop o Cursor:

{
  "mcpServers": {
    "blowsh": {
      "command": "node",
      "args": ["dist/server.js"],
      "env": {}
    }
  }
}

Ejemplo de configuración para opencode (proyecto opencode.json):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "blowsh": {
      "type": "local",
      "command": ["docker", "run", "--rm", "-i", "ghcr.io/mokhtarabadi/blowsh-mcp:latest"],
      "enabled": true,
      "timeout": 120000
    }
  },
  "permission": { "blowsh_*": "allow" }
}

La modalidad Docker no necesita binarios en el host; la imagen incluye Firefox, Browsh y html2markdown. Reinicie opencode después de guardar (la configuración se carga una vez al inicio).

Apagado ordenado

blowsh-mcp captura SIGINT/SIGTERM y garantiza que Browsh se cierre limpiamente: sin navegadores huérfanos.

Seguridad y consideraciones

• El servidor ejecuta Browsh localmente y recupera contenido mediante HTTP localhost.

• Protección SSRF: De forma predeterminada, fetch_web/search_web/extract_links/fetch_web_batch rechazan URL que resuelven a rangos de IP loopback, privados, de enlace local o reservados (verificados mediante DNS). Establezca ALLOW_PRIVATE_URLS=true para deshabilitarla; no se recomienda.

• Sin exposición pública a menos que el servidor MCP HTTP/streamable esté explícitamente configurado.

• Nunca exponga puertos a la web abierta sin firewall.

• Utilice variables de entorno para secretos/configuración.

Extensión

Añada nuevas herramientas en src/tools/, expórtelas en src/server.ts, y documéntelas.
Los clientes de IA descubrirán automáticamente los docstrings.

Solución de problemas

• Si fetchPlain devuelve 404 o no puede renderizar JS: compruebe que Firefox y Browsh están instalados y en el PATH.

• Si Firefox no se encuentra o no se puede iniciar, establezca BROWSH_FIREFOX_PATH en .env para especificar la ruta completa a su instalación de Firefox.

• El puerto y el host de Browsh son fijos: no hay ninguna opción de entorno ni de CLI para cambiarlos.

• Para máxima seguridad, ejecútelo en un contenedor.

Licencia

MIT

Autor: Mohammad Reza Mokhtarabadi mmokhtarabadi@gmail.com