> For the complete documentation index, see [llms.txt](https://developers.oxylabs.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.oxylabs.io/integrations/es/web-scraper-api-integrations/model-context-protocol-mcp.md).

# Protocolo de contexto de modelo (MCP)

Usa Oxylabs MCP para proporcionar a los asistentes de IA herramientas de scraping web en vivo, búsqueda y extracción a través de Web Scraper API y AI Studio.

El servidor MCP de Oxylabs conecta asistentes de IA ([Claude](https://claude.ai/), [Cursor](https://www.cursor.com/), y cualquier otro [Protocolo de contexto de modelo](https://modelcontextprotocol.io/) cliente) a la web del mundo real.

Una vez conectado, tu asistente puede extraer cualquier URL (incluye renderizado de JavaScript y geolocalización), buscar en la web, rastrear sitios y extraer datos estructurados.

{% hint style="success" %}
**Código abierto y registro:** Ver el código fuente en [GitHub](https://github.com/oxylabs/oxylabs-mcp). El servidor está registrado oficialmente en el [Registro MCP](https://registry.modelcontextprotocol.io/) (`io.oxylabs/oxylabs-mcp`), [PyPI](https://pypi.org/project/oxylabs-mcp/), y [Smithery](https://smithery.ai/).
{% endhint %}

## Requisitos previos

Necesitas **al menos un** conjunto de credenciales para desbloquear sus herramientas correspondientes. Proporcionar ambos desbloquea todas las herramientas listadas a continuación.

<table><thead><tr><th width="287">Credenciales</th><th width="307">Dónde obtenerlas</th><th width="165">Desbloquea</th></tr></thead><tbody><tr><td>Web Scraper API <code>nombre de usuario</code> &#x26; <code>contraseña</code></td><td><a href="https://dashboard.oxylabs.io/">panel de Oxylabs</a> (hay una prueba gratuita disponible)</td><td>herramientas de Web Scraper API</td></tr><tr><td>clave API de AI Studio</td><td><a href="https://aistudio.oxylabs.io/settings/api-key">Configuración de AI Studio</a> (se incluyen créditos gratuitos)</td><td>herramientas de AI Studio</td></tr></tbody></table>

{% hint style="warning" %}
Configura solo las credenciales que realmente tienes. Los valores de marcador de posición exponen herramientas que fallarán al ejecutarse.
{% endhint %}

## Herramientas disponibles

<table><thead><tr><th width="204">Herramienta</th><th width="428">Qué hace</th><th width="133">Requiere</th></tr></thead><tbody><tr><td><code>universal_scraper</code></td><td>Extrae cualquier URL. Renderizado opcional de JavaScript, geolocalización, salida en Markdown/HTML</td><td>Web Scraper API</td></tr><tr><td><code>google_search_scraper</code></td><td>Resultados de Google Search, opcionalmente analizados en JSON estructurado</td><td>Web Scraper API</td></tr><tr><td><code>amazon_search_scraper</code></td><td>Páginas de resultados de búsqueda de Amazon, opcionalmente analizadas</td><td>Web Scraper API</td></tr><tr><td><code>amazon_product_scraper</code></td><td>Páginas individuales de productos de Amazon</td><td>Web Scraper API</td></tr><tr><td><code>ai_scraper</code></td><td>Extracción impulsada por IA desde cualquier URL (JSON, CSV, Markdown, TOON)</td><td>AI Studio</td></tr><tr><td><code>ai_crawler</code></td><td>Rastreo multipágina y recopilación de datos guiados por prompt </td><td>AI Studio</td></tr><tr><td><code>ai_browser_agent</code></td><td>Control del navegador guiado por prompt: navegar, hacer clic, rellenar formularios</td><td>AI Studio</td></tr><tr><td><code>ai_search</code></td><td>Búsqueda web con contenido Markdown opcional de cada resultado</td><td>AI Studio</td></tr><tr><td><code>ai_map</code></td><td>Mapea URLs de sitios web</td><td>AI Studio</td></tr><tr><td><code>generate_schema</code></td><td>Genera esquemas de extracción personalizados para las herramientas de AI Studio</td><td>AI Studio</td></tr></tbody></table>

## Elige cómo conectarte

<table data-header-hidden><thead><tr><th width="117"></th><th>Alojado (recomendado)</th><th>Local</th></tr></thead><tbody><tr><td></td><td><a href="#option-1-hosted-server-recommended"><strong>Servidor alojado</strong></a> (recomendado)</td><td><a href="#option-2-run-the-server-locally"><strong>Servidor local</strong></a></td></tr><tr><td><strong>Instalar</strong></td><td>Ninguno</td><td><a href="https://docs.astral.sh/uv/">uv</a> + <code>uvx oxylabs-mcp</code></td></tr><tr><td><strong>Punto final</strong></td><td><code>https://mcp.oxylabs.io/mcp</code></td><td>Cursor/Claude inician el proceso</td></tr><tr><td><strong>Credenciales</strong></td><td>Encabezados HTTP</td><td>Variables de entorno</td></tr><tr><td><strong>Ideal para</strong></td><td>Configuración más rápida, sin gestión</td><td>Control sin conexión, depuración local, clientes que no pueden enviar encabezados personalizados</td></tr></tbody></table>

## Método 1: servidor alojado (recomendado)

Conéctate al servidor MCP alojado de Oxylabs:

```
https://mcp.oxylabs.io/mcp
```

Pasa las credenciales como encabezados de la solicitud:

<table><thead><tr><th width="240">Credencial</th><th>Encabezado</th></tr></thead><tbody><tr><td>Web Scraper API</td><td><code>Authorization: Basic &#x3C;base64(username:password)></code></td></tr><tr><td>AI Studio</td><td><code>X-Oxylabs-AI-Studio-Api-Key: &#x3C;your API key></code></td></tr></tbody></table>

{% hint style="warning" %}
**Nota:** Incluye solo los encabezados de las credenciales que tienes.
{% endhint %}

### Claude Code

Instálalo directamente en la línea de comandos:

```bash
claude mcp add --transport http oxylabs https://mcp.oxylabs.io/mcp \
  --header "Authorization: Basic $(echo -n 'YOUR_USERNAME:YOUR_PASSWORD' | base64)" \
  --header "X-Oxylabs-AI-Studio-Api-Key: YOUR_API_KEY"
```

Omite un `--header` línea si no tienes esa credencial.

### Claude Desktop

El editor de configuración integrado de Claude Desktop usa servidores locales (`comando`) servidores. Para el endpoint alojado, usa Claude Code con el comando HTTP anterior, o [ejecuta el servidor localmente](#claude-desktop-2) y apunta Claude Desktop a esa configuración.

### Cursor

1. Abre **Configuración de Cursor** → **Personalizar** en la barra lateral → **MCPs**
2. Haz clic en **+ Nuevo**
3. Elige **Usuario** (todos los proyectos) o **Proyecto** (solo el espacio de trabajo)
4. Añade lo siguiente al `mcp.json`:<br>

   ```json
   {
     "mcpServers": {
       "oxylabs": {
         "url": "https://mcp.oxylabs.io/mcp",
         "headers": {
           "Authorization": "Basic <base64 of username:password>",
           "X-Oxylabs-AI-Studio-Api-Key": "YOUR_API_KEY"
         }
       }
     }
   }
   ```
5. Guarda, luego confirma que el servidor esté habilitado en **Personalizar → MCPs**.

{% hint style="info" %}
**Nota:** *Usuario* escribe en `~/.cursor/mcp.json`. *Espacios de trabajo* escribe en `.cursor/mcp.json` en el espacio de trabajo elegido. Si ambos definen el mismo nombre de servidor, la *configuración del espacio de trabajo* tiene prioridad.
{% endhint %}

## Método 2: servidor local

El servidor está disponible en nuestro [repositorio de PyPI](https://pypi.org/project/oxylabs-mcp/).&#x20;

Si aún no está instalado, instala el [paquete uv](https://docs.astral.sh/uv/) según el sistema operativo elegido:

{% tabs %}
{% tab title="macOS / Linux" %}

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

{% endtab %}

{% tab title="Windows" %}

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

{% endtab %}
{% endtabs %}

Las credenciales se pasan como variables de entorno (define **solo** las que tienes):

| Variable                    | Descripción                          |
| --------------------------- | ------------------------------------ |
| `OXYLABS_USERNAME`          | nombre de usuario de Web Scraper API |
| `OXYLABS_PASSWORD`          | contraseña de Web Scraper API        |
| `OXYLABS_AI_STUDIO_API_KEY` | clave API de AI Studio               |

### Claude Code

```bash
claude mcp add oxylabs -- command uvx args oxylabs-mcp \
  --env OXYLABS_USERNAME=YOUR_USERNAME \
  --env OXYLABS_PASSWORD=YOUR_PASSWORD \
  --env OXYLABS_AI_STUDIO_API_KEY=YOUR_API_KEY
```

{% hint style="info" %}
Ruta de configuración manual para Claude Code: `~/.config/claude/mcp.json` (macOS/Linux) o `%USERPROFILE%\.config\claude\mcp.json` (Windows). La estructura JSON coincide con Claude Desktop.
{% endhint %}

### Claude Desktop

1. Abre **Claude → Configuración → Desarrollador → Editar configuración**
2. Añade lo siguiente a `claude_desktop_config.json`:<br>

   ```json
   {
     "mcpServers": {
       "oxylabs": {
         "command": "uvx",
         "args": ["oxylabs-mcp"],
         "env": {
           "OXYLABS_USERNAME": "YOUR_USERNAME",
           "OXYLABS_PASSWORD": "YOUR_PASSWORD",
           "OXYLABS_AI_STUDIO_API_KEY": "YOUR_API_KEY"
         }
       }
     }
   }
   ```
3. Reinicia Claude Desktop

### Cursor

1. Abre **Configuración de Cursor** → **Personalizar** en la barra lateral → **MCPs**
2. Haz clic en **+ Nuevo**
3. Elige **Usuario** (todos los proyectos) o **Proyecto** (solo el espacio de trabajo)
4. Añade lo siguiente al `mcp.json`:<br>

   ```json
   {
     "mcpServers": {
       "oxylabs": {
         "command": "uvx",
         "args": ["oxylabs-mcp"],
         "env": {
           "OXYLABS_USERNAME": "YOUR_USERNAME",
           "OXYLABS_PASSWORD": "YOUR_PASSWORD",
           "OXYLABS_AI_STUDIO_API_KEY": "YOUR_API_KEY"
         }
       }
     }
   }
   ```
5. Guarda, luego confirma que el servidor esté habilitado en **Personalizar → MCPs**.

{% hint style="info" %}
**Nota:** *Usuario* escribe en `~/.cursor/mcp.json`. *Espacios de trabajo* escribe en `.cursor/mcp.json` en el espacio de trabajo elegido. Si ambos definen el mismo nombre de servidor, la *configuración del espacio de trabajo* tiene prioridad.
{% endhint %}

## Verifica la configuración

Después de conectarte, pídele a tu asistente algo que requiera datos web en vivo (p. ej. `“Extrae https://ip.oxylabs.io y devuelve el contenido como Markdown.”`):

{% stepper %}
{% step %}
Confirma que el `oxylabs` servidor aparece y está habilitado en la lista MCP de tu cliente.
{% endstep %}

{% step %}
Aprueba la llamada a la herramienta cuando se te solicite (los clientes preguntan antes de ejecutar herramientas MCP de forma predeterminada).
{% endstep %}

{% step %}
Si la llamada falla, revisa las credenciales y los registros del cliente (Cursor: **Salida → Registros MCP**).
{% endstep %}
{% endstepper %}

## Solución de problemas

<table><thead><tr><th width="251">Error</th><th>Solución</th></tr></thead><tbody><tr><td>El servidor no aparece en el cliente</td><td>Reinicia la aplicación después de editar la configuración. Confirma que el JSON sea válido.</td></tr><tr><td>Las herramientas aparecen en la lista pero las llamadas fallan</td><td>Credenciales de marcador de posición, Base64 incorrecto o encabezado/env faltante para esa herramienta.</td></tr><tr><td>La URL alojada no se conecta</td><td>El cliente puede no admitir encabezados personalizados; usa la configuración local.</td></tr><tr><td><code>uvx</code> / no se encuentra</td><td>Instalar <a href="https://docs.astral.sh/uv/">uv</a> y asegúrate de que esté en tu <code>PATH</code>.</td></tr><tr><td>La interfaz de Cursor se ve diferente</td><td>Omite la interfaz y edita <code>mcp.json</code> directamente (las etiquetas pueden cambiar entre versiones de Cursor).</td></tr></tbody></table>

{% hint style="success" %}
Si tienes problemas o solicitudes de funciones, abre un issue en GitHub o contacta con el soporte 24/7 de Oxylabs en [**support@oxylabs.io**](mailto:support@oxylabs.io).
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developers.oxylabs.io/integrations/es/web-scraper-api-integrations/model-context-protocol-mcp.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.