Hugging Face smolagents + Scrapeless MCP: Construye un raspador web de IA en Python

Resumen:

• Un agente de Hugging Face obtiene 21 herramientas web en vivo desde un único endpoint MCP. Apuntar ToolCollection.from_mcp a https://api.scrapeless.com/mcp proporciona a los smolagents el control del navegador del CodeAgent, raspado de páginas y búsqueda y tendencias de Google, mientras que el renderizado, el enrutamiento por proxy y la anti-detección permanecen del lado del servidor.
• La ruta alojada es Python puro. HTTP transmitible con un encabezado x-api-token reemplaza cualquier proceso de servidor local: sin Node.js, un pip install "smolagents[mcp]".
• La superficie de herramientas funciona antes que un modelo. Una simple llamada a la función scrape_markdown devuelve una página en vivo como markdown limpio: 4,249 caracteres para la página de demostración en esta guía, para que puedas probar la conexión con solo una clave de API de Scrapeless.
• Un raspador de IA extrae por significado, no por selector. El agente lee el markdown y devuelve los campos que solicitas, por lo que un rediseño de sitio que rompería un script de selector CSS generalmente no te cuesta nada.
• El único requisito adicional es una clave de modelo. La lista de herramientas, las llamadas directas a herramientas y la construcción de agentes funcionan sin una; solo el intercambio de razonamiento necesita un token de Hugging Face o otro proveedor compatible.
• Gratis para empezar. Crea tu clave de API en el plan gratuito en app.scrapeless.com.

Lo que esta integración permite

Un raspador basado en selectores es una apuesta a que la página objetivo nunca cambia, y esa apuesta se pierde a menudo. Un raspador de IA toma una posición diferente: obtiene la página como texto limpio, deja que un modelo de lenguaje extraiga los campos que deseas y deja de preocuparse por qué div contiene el precio esta semana.

smolagents es la biblioteca de pequeños agentes de Hugging Face: sus agentes escriben Python para llamar herramientas en lugar de emitir llamadas a herramientas JSON. Lo que le falta por sí solo es una forma de acceder a la web en vivo. Esa es la función del Protocolo de Contexto del Modelo: la especificación del Protocolo de Contexto del Modelo define cómo un servidor publicita herramientas tipadas que cualquier cliente puede listar e invocar. Si el protocolo en sí es nuevo para ti, la introducción sobre qué es MCP y cómo funciona cubre el concepto de principio a fin.

Conecta los dos y obtienes un raspador de IA programático en unas pocas docenas de líneas de Python: smolagents proporciona el bucle de razonamiento, el servidor Scrapeless MCP proporciona obtención, renderizado y búsqueda como herramientas llamables. Esta guía construye ese raspador paso a paso y muestra exactamente qué partes funcionan con nada más que una clave de Scrapeless.

Por qué Scrapeless MCP

El servidor Scrapeless MCP expone la infraestructura de raspado como 21 herramientas tipadas, y el trabajo pesado ocurre en el servidor, no en tu proceso. scrape_html, scrape_markdown y scrape_screenshot capturan páginas únicas en diferentes formas. Dieciséis herramientas browser_* operan sesiones de navegador en la Navegador de Raspado: un navegador de nube anti-detección impulsado por Chromium desarrollado internamente, para trabajos donde un agente debe hacer clic, escribir y desplazarse. google_search y google_trends cubren el descubrimiento.

Tres propiedades son importantes para esta construcción:

• Una clave, transporte alojado. La misma clave de API de Scrapeless que impulsa el resto de la plataforma autentica el endpoint MCP. Tu proceso de Python nunca lanza un navegador o un servidor Node.
• Prueba sin modelo. Las herramientas se enumeran y ejecutan sin ningún LLM en el medio, por lo que la integración puede ser probada capa por capa en lugar de depurada a través del razonamiento de un agente.
• Un camino de extracción primero en markdown. La captura en markdown de una página es una fracción del tamaño de su HTML crudo, lo que significa menos tokens por extracción y menos ruido para que el modelo lea. scrape_markdown devuelve exactamente eso.

El mismo endpoint también se conecta a LangChain si esa es tu pila: la guía LangChain + Scrapeless MCP cubre la misma superficie desde el lado del adaptador.

Requisitos previos

• Python 3.10 o más reciente: las ejecuciones en esta guía usaron Python 3.12.
• Una clave de API de Scrapeless desde el panel de control: la documentación para desarrolladores cubre la creación de la clave y la referencia del endpoint.
• Solo para el viaje de ida y vuelta final del agente: un token de Hugging Face (o credenciales para cualquier proveedor de modelos que smolagents soporte). Cada paso anterior se ejecuta sin él.

Instalar y configurar

Un paquete con una extra trae la biblioteca del agente y la infraestructura del cliente MCP. Estas versiones son las que se utilizaron para escribir esta guía: smolagents 1.26.0, mcp 1.27.1, mcpadapt 0.1.20:

pip install "smolagents[mcp]==1.26.0"

Exporta tu clave para que los scripts puedan leerla desde el entorno en lugar de desde el código fuente:

export SCRAPELESS_API_KEY="sk_tu_clave_aquí"

Conectar a través de HTTP transmitible y listar las herramientas

La conexión es un diccionario, no un archivo de configuración. ToolCollection.from_mcp acepta los mismos parámetros que el cliente HTTP transmitible subyacente, por lo que la URL del endpoint, el nombre del transporte y el encabezado de autenticación viajan en un literal:

# connect_and_list.py — apretón de manos con el servidor MCP de Scrapeless, listar las herramientas
import os

from smolagents import ToolCollection

server = {
    "url": "https://api.scrapeless.com/mcp",
    "transport": "streamable-http",
    "headers": {"x-api-token": os.environ["SCRAPELESS_API_KEY"]},
}

with ToolCollection.from_mcp(server, trust_remote_code=True, structured_output=False) as tc:
    names = sorted(tool.name for tool in tc.tools)
    print(f"Cuenta de herramientas: {len(names)}")
    print("\n".join(names))

El administrador de contexto posee el ciclo de vida de la conexión: realiza el apretón de manos de MCP al entrar y se desconecta limpiamente al salir. Un parámetro merece una mención: la especificación de herramientas MCP permite a un servidor devolver resultados como texto simple o contenido estructurado, y las herramientas de Scrapeless devuelven texto — así que pasa structured_output=False explícitamente. smolagents 1.26 advierte siempre que el parámetro se omite, porque su valor predeterminado está programado para cambiar en una versión futura.

Un apretón de manos correcto imprime Cuenta de herramientas: 21 seguido de los nombres: dieciséis herramientas browser_*, google_search, google_trends, scrape_html, scrape_markdown, y scrape_screenshot.

También existe una ruta stdio, para clientes que prefieren lanzar un proceso de servidor local — las mismas 21 herramientas detrás de un ciclo de vida diferente:

{
  "mcpServers": {
    "scrapeless": {
      "command": "npx",
      "args": ["-y", "scrapeless-mcp-server"],
      "env": { "SCRAPELESS_KEY": "sk_tu_clave_aquí" }
    }
  }
}

Para una construcción solo de Python, HTTP transmitible es el camino más corto: nada que instalar más allá de pip, nada que mantener funcionando.

Obtén tu clave API en el plan gratuito: [app.scrapeless.com](https://app.scrapeless.com/passport/login/?utm_source=website&utm_medium
add_base_tools=False mantiene la caja de herramientas solo con las herramientas MCP más el final_answer incorporado del agente. Para un scraper que debe obtener páginas y nada más, puedes restringirlo aún más: pasa solo la herramienta que deseas, como en tools=[t for t in tc.tools if t.name == "scrape_markdown"], y el modelo no puede físicamente desviarse hacia sesiones del navegador o llamadas de búsqueda que no necesita. Una caja de herramientas más pequeña también significa un aviso del sistema más corto y menos errores del modelo.

Uso impulsado por aviso: la ejecución del scraper de IA

El paso de extracción es un aviso, no un analizador. Le dices al agente qué página leer y qué campos devolver, y el agente decide llamar a scrape_markdown, lee el resultado y reúne la respuesta: smolagents describe cada herramienta al modelo con entradas tipadas, la misma estructura la especificación JSON Schema define para restricciones de campo legibles por máquina.

Nota: Este paso final es la única brecha de requisito en esta guía: el ida y vuelta del agente necesita un proveedor de modelo. Configura HF_TOKEN con un token de Hugging Face (o configura otro proveedor que smolagents soporte) antes de ejecutarlo. Cada bloque anterior se ejecuta solo con la clave de Scrapeless.

# run_scraper.py — el ida y vuelta del modelo (requiere HF_TOKEN u otro proveedor)
result = agent.run(
    "Llama a scrape_markdown en https://quotes.toscrape.com/ y devuelve un array JSON "
    "de las citas en la página. Cada ítem debe tener exactamente estas claves: "
    "texto (cadena), autor (cadena), etiquetas (array de cadenas). "
    "Devuelve solo el array JSON, sin comentarios."
)
print(result)

La forma del aviso controla la forma de la salida. Nombrar las claves y tipos exactos, exigir "solo el array JSON" y mantener una página por ejecución te da una salida que puedes json.loads y validar en downstream. Cuando un campo falta en la página, instruye al agente a usar null en lugar de inventar un valor: los modelos llenan huecos con confianza a menos que se les diga que no lo hagan.

Lo que obtienes de vuelta

Desde la capa de obtención, obtienes markdown como una cadena: el título de la página como un encabezado, el texto del enlace preservado en corchetes, el texto del cuerpo en orden de lectura. La captura de 4,249 caracteres del sitio de citas comienza así:

# [Citas para Scraper](https://quotes.toscrape.com/)

[Iniciar sesión](https://quotes.toscrape.com/login)

“El mundo tal como lo hemos creado es un proceso de nuestro pensamiento.

Desde la ejecución del agente, obtienes cualquier contrato que tu aviso haya impuesto: aquí, un array JSON de objetos {texto, autor, etiquetas}, uno por cita en la página. El valor del arreglo se muestra el día en que el sitio objetivo cambia sus nombres de clase: el markdown aún contiene las citas, el aviso aún nombra los campos y el scraper aún devuelve el mismo esquema mientras que un script basado en selectores no devuelve nada.

Conclusión

La integración son tres movimientos pequeños: apunta ToolCollection.from_mcp al endpoint alojado, prueba la capa de obtención con una llamada directa a scrape_markdown, luego vincula las herramientas a un CodeAgent y deja que un aviso realice la extracción. Cada capa es testeable por sí misma, solo la última necesita una clave de modelo, y la parte más propensa a romperse en un scraper clásico — el análisis — es la parte que el modelo absorbe.

¿Listo para Darle a Tu Agente una Superficie Web Real?

El endpoint MCP se autentica con la misma clave API que el resto de la plataforma Scrapeless: los planes y volúmenes incluidos están en la página de precios. Crea una clave en el plan gratuito en app.scrapeless.com y el script de apretón de manos anterior imprimirá tus 21 herramientas en menos de un minuto.

FAQ

P: ¿Qué es un scraper de IA?

Un scraper de IA es un scraper que utiliza un modelo de lenguaje para el paso de extracción en lugar de reglas de análisis escritas a mano. Un scraper convencional une la obtención y el análisis a una estructura de página específica; un scraper de IA obtiene la página como texto y le pide a un modelo que devuelva campos nombrados, lo que sigue funcionando a través de cambios de diseño que romperían selectores.

P: ¿Necesito un token de Hugging Face para llamar a las herramientas de Scrapeless?

No. Listar herramientas, llamar a scrape_markdown directamente y construir el CodeAgent se autentican solo con la clave API de Scrapeless. El token de Hugging Face (o la clave de otro proveedor) es necesario para exactamente una cosa: el ida y vuelta de razonamiento agent.run().

P: ¿Debería conectarme a través de HTTP transmitible o stdio?

Usa HTTP transmitible para proyectos de Python: no necesita ningún proceso local y se autentica con un encabezado. El transporte stdio (npx -y scrapeless-mcp-server, autenticado a través de la variable de entorno SCRAPELESS_KEY) es adecuado para clientes MCP de escritorio que gestionan procesos de servidor por sí mismos. Ambos transportes exponen la misma superficie de herramientas.
P: ¿Puede el agente usar solo una herramienta en lugar de las 21?

Sí. Filtra la colección antes de construir el agente — tools=[t for t in tc.tools if t.name == "scrape_markdown"] — y el modelo solo ve esa herramienta. Para scrapers de un solo propósito, esta es la forma recomendada: el aviso del sistema se reduce y el modelo no puede iniciar sesiones de navegador que nunca pretendiste.

P: ¿Qué pasa con las páginas con mucho JavaScript o las páginas detrás de desafíos anti-bot?

El renderizado ocurre del lado del servidor, por lo que tu código Python no cambia. scrape_html y scrape_markdown manejan páginas que necesitan ejecución de JavaScript, y las herramientas browser_* gestionan sesiones completas de navegador en la nube para flujos que requieren hacer clic o escribir. El enrutamiento de proxy y la anti-detección son parte del servicio administrado y no algo que el agente deba razonar.

P: ¿Qué modelos funcionan con smolagents?

Cualquier proveedor que la biblioteca soporte. InferenceClientModel cubre modelos servidos a través de proveedores de inferencia de Hugging Face, y la biblioteca también incluye OpenAIModel, AzureOpenAIModel, AmazonBedrockModel, LiteLLMModel, y backend locales como TransformersModel — consulta la referencia de modelos de smolagents para la lista actual. El lado de MCP es agnóstico al modelo: las herramientas lucen idénticas independientemente del modelo que razone sobre ellas.

P: ¿Es legal raspar con un agente de IA?

Las mismas reglas se aplican que para cualquier scraper: solo recopila páginas públicas, respeta los términos y directivas de robots del sitio objetivo, mantiene los volúmenes limitados y maneja cualquier dato personal bajo las leyes de privacidad que te correspondan. Un agente cambia cómo ocurre la extracción, no lo que se te permite recopilar — cuando tengas dudas, consulta a un abogado antes de aumentar una carga de trabajo.