ZenRows MCP

El servidor ZenRows MCP le da a tu agente acceso a toda la web, incluidos todos los sitios que bloquean bots.

GitHub
20

Documentación

Zenrows MCP

Servidor Zenrows MCP

El servidor Zenrows MCP (Model Context Protocol) es la forma estándar en que los sistemas de IA utilizan la infraestructura de datos web de Zenrows. Una sola conexión le da a tu asistente de IA, agente o aplicación acceso confiable y en tiempo real a la web en vivo, incluida la web protegida.

npm version MIT License

📚 Documentación completa: docs.zenrows.com/mcp/overview

Por qué Zenrows MCP

  • Accede a sitios que normalmente bloquean bots. Obtén acceso confiable a sitios protegidos a escala, sin tener que crear tu propio manejo anti-bots.
  • Infraestructura de datos web gestionada. La rotación de proxies, la orquestación de navegadores headless, el manejo anti-bots y la gestión de sesiones se ejecutan en la infraestructura de Zenrows.
  • Conéctalo a cualquier IA que ya uses. Funciona con cualquier cliente MCP, incluidos asistentes de IA, frameworks de agentes, SDKs de IA, plugins de IDE y aplicaciones personalizadas.
  • En lenguaje natural, sin código de scraping. Describe la tarea de forma natural y la IA elige la herramienta adecuada. Sin selectores, sin gestión de proxies, sin ajustes anti-bots.

Inicio rápido

Zenrows MCP admite dos opciones de transporte. Ambas exponen el mismo conjunto de herramientas y capacidades. Elige la que se adapte a tu cliente.

Servidor MCP remoto

Usa el servidor MCP remoto alojado de Zenrows cuando tu aplicación de IA llame directamente a una API de LLM. El servidor se ejecuta en la infraestructura de Zenrows, por lo que no hay nada que instalar, configurar o actualizar.

URL del servidor:

https://mcp.zenrows.com/mcp

Transporte: HTTP Streamable

Autenticación: OAuth o clave de API como token Bearer. Pasa tu clave de API de Zenrows en el encabezado Authorization en cada solicitud (o completa OAuth en clientes que lo admitan).

Authorization: Bearer YOUR_ZENROWS_API_KEY

La mayoría de los clientes MCP aceptan esto mediante un campo abreviado authorization en la configuración de la herramienta y lo reenvían automáticamente como token Bearer. Algunos clientes usan un campo de formato libre headers en su lugar. Cualquiera de los dos enfoques funciona.

El MCP remoto no crea cuentas automáticamente. Usa OAuth "Crear cuenta gratuita" en el cliente, o pasa una clave de API existente.

Ejemplo: API de Respuestas de OpenAI

import os
from openai import OpenAI

ZENROWS_API_KEY = os.environ["ZENROWS_API_KEY"]
client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])

response = client.responses.create(
    model="gpt-5",
    tools=[
        {
            "type": "mcp",
            "server_label": "zenrows",
            "server_description": "Web scraping MCP server for accessing live web content.",
            "server_url": "https://mcp.zenrows.com/mcp",
            "authorization": ZENROWS_API_KEY,
            "require_approval": "never",
        }
    ],
    input="Visit https://news.ycombinator.com/ and summarize the three most recent posts.",
)

print(response.output_text)

Para el tutorial completo con ejemplos específicos de frameworks, consulta la documentación del servidor MCP remoto.

Servidor MCP local

Usa la configuración local stdio cuando tu cliente MCP ejecute el servidor como un subproceso local en lugar de llamar a una URL remota. Esta es la configuración estándar para herramientas de escritorio de IA y plugins de IDE, incluidos Claude Desktop, Claude Code, Cursor, Windsurf, VS Code, Zed e IDEs de JetBrains.

Paquete: @zenrows/mcp en npm

Autenticación:

  1. Variable de entorno ZENROWS_API_KEY, o
  2. Clave previamente almacenada en ~/.zenrows/secrets.json, o
  3. Registro automático (predeterminado): si no se establece ninguna, stdio aprovisiona una cuenta del plan gratuito mediante POST /api/agent/signup, guarda la clave + metadatos de reclamación en ~/.zenrows/ (secrets.json + account.json, modo 0600) e imprime una URL de reclamación en stderr. Puedes optar por no participar con ZENROWS_AUTO_SIGNUP=false.

Requisitos: Node.js instalado (para que npx funcione).

Configuración (con tu propia clave):

{
  "mcpServers": {
    "zenrows": {
      "command": "npx",
      "args": ["-y", "@zenrows/mcp"],
      "env": {
        "ZENROWS_API_KEY": "YOUR_ZENROWS_API_KEY"
      }
    }
  }
}

Configuración cero (registro automático):

{
  "mcpServers": {
    "zenrows": {
      "command": "npx",
      "args": ["-y", "@zenrows/mcp"]
    }
  }
}

Opcional: ZENROWS_CRAWL_API_BASE establece la URL base de la API de Crawl para las herramientas crawl_* (predeterminado https://api.zenrows.com/v1). Configúralo solo para apuntar esas herramientas a otra implementación.

La ubicación exacta de esta configuración varía según el cliente. Consulta las guías de configuración por cliente para conocer la ruta del archivo según tu cliente.

Herramientas

Zenrows MCP expone estas familias de herramientas:

HerramientaPropósito
scrapeContenido de página completa → Markdown, texto plano, HTML, PDF o captura de pantalla (además de salidas auxiliares).
extractJSON estructurado (extract=auto, autoparse o css_extractor) + banderas de sigilo opcionales. extract=auto actualmente es gratuito (puede aplicarse facturación más adelante) y funciona en cualquier dominio que Zenrows haya preparado, con cualquier clave de API; en un dominio aún no preparado (REQS007) recurre al autoparse.
batch_create / batch_status / batch_results / batch_cancel / batch_waitExpansión de la API de Batch en la nube (async.api.zenrows.com). Mismos créditos que Fetch; un 403 se asigna a BATCH_ACCESS_DENIED. No es browser_batch.
crawl_create / crawl_get / crawl_results / crawl_content / crawl_download / crawl_list / crawl_stop / crawl_waitAPI de Crawl (api.zenrows.com/v1/crawls). Nueva. Crawl aún está en evolución: se agregarán nuevas funciones, los límites pueden ajustarse y el changelog anuncia cada cambio. Proporciona una URL de inicio y obtén las URLs detrás de ella en el mismo dominio registrable (los subdominios cuentan), opcionalmente con el HTML de cada página (output_format: "html"). crawl_create devuelve todo a la vez; llama a crawl_wait (recuentos y las primeras 20 URLs), luego crawl_download para guardar cada resultado en un archivo local de líneas JSON (predeterminado ~/.zenrows/crawls/<crawl_id>.jsonl; un path debe permanecer dentro de ~/.zenrows/crawls; un archivo existente se conserva a menos que overwrite: true; el servidor alojado no escribe archivos y devuelve la URL de descarga y un comando curl en su lugar), o crawl_results para paginar a través de ellos. Deja depth fuera de crawl_create para no tener límite de profundidad: el crawl sigue enlaces hasta que max_pages o max_items (predeterminado 100 cada uno) lo detenga, y cada página obtenida se factura como un scrape. Establece idempotency_key en crawl_create para que un reintento sea seguro. crawl_content toma crawl_id y content_id (un id de contenido o el content_url de un resultado). Las lecturas reintentan en 429, 502, 503, 504 y errores de red (hasta 3 veces, respetando Retry-After hasta 30 segundos); crawl_create reintenta solo con un idempotency_key, y nunca en 429; crawl_stop reintenta en 429, 502, 503 y 504 (repetir una detención es seguro; un 503 crawl_busy significa que la detención aún no se guardó), hasta 3 veces y 50 segundos como máximo en total, y devuelve CRAWL_BUSY si persiste un crawl_busy. Puede devolver CRAWL_NOT_ENABLED (Crawl no está habilitado para esta cuenta).
browser_*Más de 30 herramientas para automatización completa del navegador (navegación, clics, formularios, JS, cookies, pestañas, sesiones).

La IA selecciona la herramienta adecuada según tu indicación. No llamas a las herramientas directamente en el código.

Consulta la referencia completa de herramientas para conocer cada herramienta, parámetro y valor de retorno.

Desarrollo

git clone https://github.com/ZenRows/zenrows-mcp
cd zenrows-mcp
npm install
cp .env.example .env   # Optional: add your API key (stdio can auto-signup)
npm run dev            # Run with .env loaded (requires Node.js 20.6+)
npm run build          # Compile to dist/
npm run inspect        # Open the MCP inspector UI

Ejecutar la prueba de extremo a extremo de Crawl

npm test permanece sin conexión. npm run test:e2e impulsa las herramientas crawl_* a través de un cliente MCP real contra una API de Crawl en vivo: crea un crawl pequeño (profundidad 1, como máximo 3 URLs y 5 páginas) de la URL de inicio que le des, espera a que termine, lee sus resultados y una página, lista los crawls, detiene el crawl finalizado y verifica el error de no encontrado. Se omite a menos que se establezcan las tres primeras variables:

  • ZENROWS_API_KEY: una clave con acceso a Crawl.
  • ZENROWS_CRAWL_API_BASE: la base de la API de Crawl, por ejemplo https://api.zenrows.com/v1. Apúntala a una implementación local o de staging para probar contra esa en su lugar.
  • ZENROWS_E2E_CRAWL_URL: la URL de inicio para rastrear, una página de listado cuyos enlaces lleven a páginas de elementos.
  • ZENROWS_E2E_CRAWL_INCLUDE (opcional): un patrón de inclusión; cuando se establece, la prueba verifica que cada URL de resultado lo contenga.
export ZENROWS_API_KEY=...            # a key with Crawl access
export ZENROWS_CRAWL_API_BASE=https://api.zenrows.com/v1
export ZENROWS_E2E_CRAWL_URL=https://example.com/products/
export ZENROWS_E2E_CRAWL_INCLUDE=/product/
npm run test:e2e

El crawl se factura a la cuenta de la clave (como máximo 5 obtenciones de páginas) y cuenta contra el límite de trabajos activos de la cuenta (3 por defecto), compartido con sus trabajos de Batch. Cuando la cuenta alcanza ese límite, la prueba espera y reintenta hasta 5 minutos.

Lanzamientos

Fusiona PRs con títulos de Conventional Commit, por ejemplo fix(extract): ... o feat(crawl): .... fix, feat y perf necesitan un ámbito.

Después de cada fusión en main, release-please abre o actualiza el PR chore: release X.Y.Z. Establece la versión en package.json, package-lock.json y server.json. No los cambies manualmente.

Para lanzar, fusiona ese PR. El flujo de trabajo de Release ejecuta las verificaciones, crea la etiqueta vX.Y.Z y el lanzamiento de GitHub, e inicia el flujo de trabajo de Publish. Ese flujo de trabajo publica en npm y el Registro MCP, envía la imagen GHCR y despliega el servidor alojado.

Para publicar una etiqueta existente nuevamente, ejecuta el flujo de trabajo de Release manualmente desde main con esa etiqueta.

Si las verificaciones fallan después de fusionar el PR de lanzamiento

El PR de lanzamiento no ejecuta CI, por lo que sus verificaciones se ejecutan por primera vez después de la fusión. Si fallan, main ya tiene la nueva versión, pero no hay etiqueta, y el PR de lanzamiento fusionado conserva la etiqueta autorelease: pending, lo que bloquea el siguiente PR de lanzamiento. Para recuperarse:

  1. Corrige el problema en un PR normal y fúndelo.
  2. Crea el lanzamiento en ese commit de corrección, con la versión de .release-please-manifest.json: gh release create vX.Y.Z --target <fix commit> --title vX.Y.Z --generate-notes --notes-start-tag <previous tag>
  3. En el PR de lanzamiento fusionado, reemplaza la etiqueta autorelease: pending con autorelease: tagged.
  4. Ejecuta el flujo de trabajo de Release manualmente desde main con la etiqueta vX.Y.Z.

Las solicitudes de extracción y los problemas son bienvenidos.

Recursos

Licencia

MIT