Browser MCP Server

Un servidor MCP (Model Context Protocol) que ofrece a los agentes de IA un navegador real, consciente de la detección anti-bot, mediante Zyte API — navegar páginas, hacer clic/escribir/desplazarse, tomar capturas de pantalla y extraer datos estructurados, con rotación automática de proxy/IP y evitación de baneos.

Construido con NestJS y @nestjs-mcp/server, que se comunica con el endpoint /extract de Zyte directamente por HTTP. El transporte es exclusivamente HTTP transmitible, servido sin estado en un único endpoint /mcp.

Setup

1. Copia .env.example a .env y rellena los valores:

   Variable	Obligatoria	Descripción
   ZYTE_API_KEY	sí	Tu clave de Zyte API
   ZYTE_API_BASE_URL	no	Sustituye la URL base de Zyte API (por defecto https://api.zyte.com/v1)
   PORT	no	Puerto HTTP (por defecto 3000)
   BROWSER_TIMEOUT_MS	no	Tiempo de espera por petición para las llamadas a Zyte (por defecto 30000)
   BROWSER_MAX_RETRIES	no	Reintentos para respuestas de límite de peticiones (429/503) y bloqueo temporal (520), con retroceso exponencial (por defecto 2)

2. Instala las dependencias y arranca el servidor:

   pnpm install
   pnpm run start:dev

   El endpoint MCP se sirve en http://localhost:3000/mcp.

Related MCP server: Stealth Browser MCP

Tools

browser_browse, browser_screenshot y browser_extract aceptan un sessionId opcional (devuelto por una llamada anterior) para reutilizar la misma dirección IP y el conjunto de cookies en múltiples llamadas a las herramientas — útil para mantener la sesión iniciada o mantener una IP estable durante una tarea de varios pasos. Ten en cuenta que, según la documentación de sesiones de Zyte, esto no conserva el estado real del navegador/pestaña (entrada de formularios en la página, posición de desplazamiento, modales abiertos, etc.) entre llamadas — cada llamada carga una página nueva con la misma identidad de red y las mismas cookies.

actions es una secuencia de pasos que se ejecutan antes de capturar el resultado: click, type, select, hover, keyPress, scrollBottom, scrollTo, waitForSelector, waitForTimeout, waitForNavigation, goto, evaluate. Las acciones que apuntan a un elemento toman un selector: { type: "css" | "xpath", value: string }.

browser_search envía a Zyte al endpoint separado /v1/search (no al /v1/extract) y acepta un domain (un motor de búsqueda compatible, p. ej. "google.com"), una query y, opcionalmente, maxResults (10-100)/geolocation/locale.

Las respuestas de límite de peticiones (429/503) y de bloqueo temporal (520) se reintentan automáticamente con retroceso exponencial, hasta BROWSER_MAX_RETRIES veces, según la guía de manejo de errores de Zyte. El resto de respuestas de error (solicitud no válida, bloqueo permanente, cuenta suspendida) aparecen de inmediato, e incluyen en el mensaje el type del error de Zyte cuando está disponible.

Conexión de un cliente

Ejemplo de configuración de un cliente MCP remoto (p. ej., Claude Desktop / Claude Code) que apunta a una instancia en ejecución:

{
  "mcpServers": {
    "browser": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

Testing

pnpm test        # unit tests (service + resolver, global fetch mocked)
pnpm run lint    # eslint
pnpm run build   # type-check + compile

Las pruebas unitarias simulan la función global fetch utilizada para llamar a Zyte. Para verificar de extremo a extremo contra la API real, ejecuta el servidor con una ZYTE_API_KEY real y usa pnpm dlx @modelcontextprotocol/inspector http://localhost:3000/mcp, o curl, para ejecutar initialize → tools/list → tools/call.