Oxylabs

Oxylabs MCP Server

El vínculo que faltaba entre los modelos de IA y la web del mundo real: una API que proporciona datos limpios y estructurados de cualquier sitio.

---

Aviso legal

Este repositorio sigue contando con soporte completo, pero si utilizas Oxylabs Web API, consulta el repositorio de Web API MCP: Web API MCP

📖 Descripción general

El servidor MCP de Oxylabs conecta los modelos de IA con la web. Les permite extraer datos de cualquier URL, renderizar páginas con mucho JavaScript, extraer y dar formato al contenido para su uso con IA, gestionar CAPTCHA y acceder a datos web con restricciones geográficas de más de 195 países.

Está basado en Model Context Protocol (MCP), el estándar abierto para conectar asistentes de IA con herramientas y datos externos.

mcp-name: io.oxylabs/oxylabs-mcp

🛠️ Herramientas MCP

Oxylabs MCP ofrece dos conjuntos de herramientas que se pueden usar juntos o por separado:

Herramientas de Oxylabs Web Scraper API

1. universal_scraper: extrae datos de cualquier URL, con renderizado opcional de JavaScript, segmentación geográfica y salida en Markdown/HTML/enlaces;
2. google_search_scraper: extrae resultados de Google Search, con la opción de analizarlos y convertirlos en JSON estructurado;
3. amazon_search_scraper: extrae páginas de resultados de búsqueda de Amazon, con la opción de analizarlas y convertirlas en JSON estructurado;
4. amazon_product_scraper: extrae datos de páginas de productos individuales de Amazon.

Herramientas de Oxylabs AI Studio

5. ai_scraper: extrae contenido de cualquier URL con extracción basada en IA, en formato JSON, CSV, Markdown o TOON;
6. ai_crawler: rastrea un sitio web desde una URL inicial según una instrucción y recopila datos de varias páginas;
7. ai_browser_agent: controla un navegador real según una instrucción — navega, hace clic, rellena formularios — y devuelve el resultado;
8. ai_search: busca en la web y, opcionalmente, devuelve el contenido Markdown de cada resultado;
9. ai_map: genera un mapa de las URL de un sitio web, filtradas por palabras clave o una instrucción;
10. generate_schema: genera un esquema JSON en formato OpenAPI para la extracción estructurada con las herramientas de IA anteriores.

✅ Requisitos previos

Antes de empezar, asegúrate de tener al menos una de las siguientes opciones:

• Cuenta de Oxylabs Web Scraper API: obtén un token de API (o tu nombre de usuario y contraseña) en el panel de Oxylabs (disponible una prueba gratuita de 1 semana);
• Clave de API de Oxylabs AI Studio: obtén tu clave de API en Oxylabs AI Studio (1000 créditos gratis).

Para ejecutar el servidor localmente (opción 2 a continuación), también necesitarás el gestor de paquetes uv:

# macOS and Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

📦 Configuración

Hay dos formas de usar el servidor: conectarse a la instancia alojada (sin instalación) o ejecutarlo localmente con credenciales en variables de entorno.

Opción 1: Servidor alojado (sin instalación)

Oxylabs ejecuta un servidor MCP alojado en:

https://mcp.oxylabs.io/mcp

Las credenciales se envían en los encabezados de las solicitudes:

Credencial	Encabezado
Token de Web Scraper API (recomendado)	Authorization: Bearer <token>
Token de Web Scraper API (alternativo)	X-Oxylabs-Api-Token
Nombre de usuario y contraseña de Web Scraper API	Authorization: Basic <base64(username:password)>
Nombre de usuario y contraseña de Web Scraper API (alt.)	X-Oxylabs-Username y X-Oxylabs-Password
AI Studio	X-Oxylabs-AI-Studio-Api-Key

Si se envían tanto un token de API como un nombre de usuario y una contraseña, se utilizará el token.

Configuración con Claude Code:

claude mcp add --transport http oxylabs https://mcp.oxylabs.io/mcp \
  --header "Authorization: Bearer YOUR_API_TOKEN" \
  --header "X-Oxylabs-AI-Studio-Api-Key: YOUR_API_KEY"

Configuración con Cursor o cualquier cliente compatible con servidores MCP remotos con encabezados personalizados:

{
  "mcpServers": {
    "oxylabs": {
      "url": "https://mcp.oxylabs.io/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_TOKEN",
        "X-Oxylabs-AI-Studio-Api-Key": "YOUR_API_KEY"
      }
    }
  }
}

El servidor también está disponible en Smithery.

Nota: los clientes que solo admiten OAuth para servidores remotos (por ejemplo, al añadir un conector personalizado en la interfaz web de claude.ai) todavía no pueden enviar encabezados; el inicio de sesión con OAuth está en nuestra hoja de ruta. Mientras tanto, utiliza la configuración local que se indica a continuación con esos clientes.

Opción 2: Ejecución local

Variables de entorno

El servidor MCP de Oxylabs admite las siguientes variables de entorno:

Nombre	Descripción	Valor predeterminado
OXYLABS_API_TOKEN	Tu token de Oxylabs Web Scraper API
OXYLABS_USERNAME	Tu nombre de usuario de Oxylabs Web Scraper API
OXYLABS_PASSWORD	Tu contraseña de Oxylabs Web Scraper API
OXYLABS_AI_STUDIO_API_KEY	Tu clave de API de Oxylabs AI Studio
LOG_LEVEL	Nivel de registro de los mensajes devueltos al cliente	INFO

Para las herramientas de Web Scraper API, configura OXYLABS_API_TOKEN o bien OXYLABS_USERNAME y OXYLABS_PASSWORD. Si se configuran ambos, se utilizará el token. Para las herramientas de AI Studio, configura OXYLABS_AI_STUDIO_API_KEY.

Todas las herramientas aparecen siempre en la lista; si se llama a una herramienta sin las credenciales que necesita, se devuelve un mensaje de error que explica qué se debe configurar.

❗ Importante: configura únicamente las variables de entorno para las que tengas credenciales reales. Los valores de marcador de posición harán que fallen las llamadas a las herramientas.

Configuración con uvx

Instala el paquete de PyPI y lo ejecuta automáticamente:

{
  "mcpServers": {
    "oxylabs": {
      "command": "uvx",
      "args": ["oxylabs-mcp"],
      "env": {
        "OXYLABS_API_TOKEN": "YOUR_API_TOKEN",
        "OXYLABS_AI_STUDIO_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Configuración con una copia local

Útil para el desarrollo: ejecuta el servidor desde un clon local de este repositorio:

{
  "mcpServers": {
    "oxylabs": {
      "command": "uv",
      "args": [
        "--directory",
        "/<absolute-path-to-folder>/oxylabs-mcp",
        "run",
        "oxylabs-mcp"
      ],
      "env": {
        "OXYLABS_API_TOKEN": "YOUR_API_TOKEN",
        "OXYLABS_AI_STUDIO_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Ejecución como servidor HTTP remoto (alojamiento propio)

El servidor también admite el transporte MCP streamable-HTTP. Inícialo con:

MCP_TRANSPORT=streamable-http MCP_HOST=0.0.0.0 MCP_PORT=8000 uvx oxylabs-mcp

Con el transporte HTTP, las credenciales se envían en cada solicitud en lugar de utilizar variables de entorno:

Credencial	Cómo enviarla
Token de Web Scraper API (recomendado)	Authorization: Bearer <token>
Token de Web Scraper API (alternativo)	Encabezado X-Oxylabs-Api-Token
Nombre de usuario y contraseña de Web Scraper API	Authorization: Basic <base64(username:password)> (autenticación HTTP Basic)
Nombre de usuario y contraseña de Web Scraper API (alt.)	Encabezados X-Oxylabs-Username y X-Oxylabs-Password
AI Studio	Encabezado X-Oxylabs-AI-Studio-Api-Key

Ejemplo de configuración del cliente:

{
  "mcpServers": {
    "oxylabs": {
      "url": "https://your-host:8000/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_TOKEN",
        "X-Oxylabs-AI-Studio-Api-Key": "YOUR_API_KEY"
      }
    }
  }
}

Todas las herramientas aparecen siempre en la lista, independientemente de las credenciales proporcionadas; si se llama a una herramienta sin las credenciales que necesita, se devuelve un mensaje de error que explica exactamente qué se debe configurar.

Configuración con Claude Desktop

Ve a Claude → Settings → Developer → Edit Config y añade una de las configuraciones anteriores al archivo claude_desktop_config.json.

Configuración con Cursor AI

Ve a Cursor → Settings → Cursor Settings → MCP. Haz clic en Add new global MCP server y añade una de las configuraciones anteriores.

📝 Registro

El servidor proporciona información adicional sobre las llamadas a las herramientas en los eventos notification/message:

{
  "method": "notifications/message",
  "params": {
    "level": "info",
    "data": "Create job with params: {\"url\": \"https://ip.oxylabs.io\"}"
  }
}

{
  "method": "notifications/message",
  "params": {
    "level": "info",
    "data": "Job info: job_id=7333113830223918081 job_status=done"
  }
}

{
  "method": "notifications/message",
  "params": {
    "level": "error",
    "data": "Error: request to Oxylabs API failed"
  }
}

✨ Funciones principales

Extrae contenido de cualquier sitio

• Extrae datos de cualquier URL, incluidas aplicaciones complejas de una sola página
• Renderiza por completo sitios web dinámicos mediante la compatibilidad con navegadores sin interfaz gráfica
• Elige entre renderizado completo de JavaScript, solo HTML o ninguno
• Emula ventanas gráficas móviles y de escritorio para un renderizado realista

Obtén automáticamente datos listos para IA

• Limpia y convierte automáticamente HTML a Markdown para mejorar la legibilidad
• Utiliza analizadores automatizados para destinos populares como Google, Amazon y otros

Gestiona CAPTCHA y restricciones geográficas

• Supera sistemas sofisticados de gestión de solicitudes automatizadas con una alta tasa de éxito
• Extrae datos de forma fiable incluso de los sitios web más complejos
• Obtén direcciones IP rotativas automáticamente de un conjunto de proxies que cubre más de 195 países

Configuración flexible y compatibilidad multiplataforma

• Configura las opciones de renderizado y análisis si es necesario
• Envía datos directamente a modelos de IA o herramientas de análisis
• Compatible con macOS, Windows y Linux

Gestión de errores y solicitudes integrada

• Gestión y notificación exhaustivas de errores
• Limitación inteligente de la frecuencia y gestión de solicitudes

¿Por qué Oxylabs MCP?  🕸️ ➜ 📦 ➜ 🤖

Imagina decirle a tu LLM «Resume la última conversación de Hacker News sobre GPT‑5» y que simplemente te responda. El servidor MCP de Oxylabs lo hace posible al encargarse de las tareas tediosas:

Qué hace Oxylabs MCP	Por qué te importa
Gestiona los bloqueos de solicitudes automatizadas con la red global de proxies de Oxylabs	Permite acceder a sitios web de forma anónima
Renderiza JavaScript en Chrome sin interfaz gráfica	Aplicaciones de una sola página, resueltas
Limpia HTML → Markdown	Listo para usar en bases de datos vectoriales o prompts
Analizadores estructurados opcionales (Google, Amazon, etc.)	Acceso en una sola línea a destinos populares

---

🛡️ Licencia

Distribuido bajo la licencia MIT. Consulta LICENSE para obtener más información.

---

Acerca de Oxylabs

Fundada en 2015, Oxylabs es una plataforma líder en el mercado para la recopilación de inteligencia web, impulsada por los más altos estándares empresariales, éticos y de cumplimiento normativo, que permite a empresas de todo el mundo obtener información basada en datos.

Soluciones creadas con este MCP:

Michelin Detour