Aluvia

El servidor MCP de Aluvia expone la gestión de sesiones del navegador, la geolocalización y las operaciones de cuenta como herramientas del Protocolo de Contexto del Modelo para agentes de IA.

GitHub

Prueba este MCPPatrocinado

Documentación

@aluvia/mcp

Automatización de navegador sin bloqueos para agentes de IA.

Deja de ser bloqueado. El servidor MCP de Aluvia expone la gestión de sesiones de navegador, la orientación geográfica y las operaciones de cuenta como herramientas del Model Context Protocol para agentes de IA. Enruta el tráfico a través de IPs premium de operadores móviles de EE. UU. y evita errores 403, CAPTCHAs y WAFs que detienen a otras herramientas. Funciona con Claude Desktop, Claude Code, Cursor, VS Code y cualquier cliente compatible con MCP.

Obtén una Clave API de Aluvia

Necesitas una clave API para ejecutar el servidor MCP. Obtén una desde el panel de Aluvia:

Regístrate o inicia sesión en dashboard.aluvia.io
En tu cuenta, abre la sección API & SDKs
Copia tu clave API

Úsala como variable de entorno: export ALUVIA_API_KEY="your-api-key" o agrega ALUVIA_API_KEY=your-api-key a un archivo .env (nunca lo subas al repositorio).

Inicio Rápido

npm install @aluvia/mcp
export ALUVIA_API_KEY="your-api-key"
npx aluvia-mcp

El servidor se ejecuta en stdio (stdin/stdout JSON-RPC) — los clientes MCP lo inician y se comunican a través de stdio.

Requisitos

Node.js 18+
Clave API de Aluvia — Consulta Obtén una Clave API de Aluvia
Playwright — Requerido para las herramientas de sesión (session_start, etc.); instálalo con npm install playwright

Instalación

npm install @aluvia/mcp

Configura tu clave API en el entorno:

export ALUVIA_API_KEY="your-api-key"

O en un archivo .env (nunca lo subas al repositorio):

ALUVIA_API_KEY=your-api-key

Configuración del Cliente

Agrega la configuración a continuación para tu cliente MCP. Reemplaza your-api-key con tu clave real.

Claude Desktop

Agrega a claude_desktop_config.json:

{
  "mcpServers": {
    "aluvia": {
      "command": "npx",
      "args": ["-y", "aluvia-mcp"],
      "env": {
        "ALUVIA_API_KEY": "your-api-key"
      }
    }
  }
}

Claude Code

Agrega a .claude/settings.json o a la configuración MCP del proyecto:

{
  "mcpServers": {
    "aluvia": {
      "command": "npx",
      "args": ["-y", "aluvia-mcp"],
      "env": {
        "ALUVIA_API_KEY": "your-api-key"
      }
    }
  }
}

Cursor

Abre Configuración → MCP
Agrega un nuevo servidor MCP
Usa:
- Comando: npx
- Argumentos: ["-y", "aluvia-mcp"]
- Variables de entorno: ALUVIA_API_KEY = tu clave

VS Code / Cursor (mcp.json)

Para configuración a nivel de espacio de trabajo, agrega .vscode/mcp.json o mcp.json:

{
  "mcpServers": {
    "aluvia": {
      "command": "npx",
      "args": ["-y", "aluvia-mcp"],
      "env": {
        "ALUVIA_API_KEY": "your-api-key"
      }
    }
  }
}

Otros Clientes MCP

Inicia con command: "npx", args: ["-y", "aluvia-mcp"] y ALUVIA_API_KEY en el entorno del proceso. Consulta la Guía del Servidor MCP para un ejemplo de cliente Node.js.

Herramientas Disponibles

Todas las herramientas devuelven JSON. En caso de éxito, isError es false. En caso de error, isError es true y el payload incluye un campo error.

Herramientas de Sesión

Herramienta	Descripción
`session_start`	Inicia una sesión de navegador con el proxy inteligente de Aluvia. Parámetros: `url` (obligatorio), `connectionId`, `headful`, `browserSession`, `autoUnblock`, `disableBlockDetection`
`session_close`	Cierra una o todas las sesiones en ejecución. Parámetros: `browserSession`, `all`
`session_list`	Lista las sesiones activas (PIDs, URLs, URLs CDP, IDs de conexión)
`session_get`	Detalles completos de la sesión, incluido el estado de detección de bloqueos y la configuración de conexión. Parámetros: `browserSession`
`session_rotate_ip`	Rota la IP de una sesión (nuevo ID de sesión). Parámetros: `browserSession`
`session_set_geo`	Establece o elimina la orientación geográfica (p. ej. `us`, `gb`, `de`). Parámetros: `geo`, `clear`, `browserSession`
`session_set_rules`	Agrega o elimina reglas de enrutamiento del proxy (nombres de host separados por comas). Parámetros: `rules`, `remove`, `browserSession`

Herramientas de Cuenta

Herramienta	Descripción
`account_get`	Información de la cuenta (saldo, plan, número de conexiones)
`account_usage`	Estadísticas de uso para un rango de fechas. Parámetros: `start`, `end` (ISO 8601)

Herramientas Geográficas

Herramienta	Descripción
`geos_list`	Lista los países disponibles para orientación geográfica (p. ej. `us`, `gb`, `de`)

Detalles completos de parámetros y respuestas: Guía del Servidor MCP — Referencia de Herramientas.

Casos de Uso

Escenario	Herramientas Usadas	Flujo
Extraer datos de un sitio protegido	`session_start`, `session_list`	Inicia con `autoUnblock: true`; el agente recibe la URL CDP para Playwright/Puppeteer
Evitar restricciones regionales	`session_start`, `session_set_geo`	Establece `geo: "us"` para acceder a contenido exclusivo de Estados Unidos
Recuperarse de un bloqueo	`session_rotate_ip`, `session_set_rules`	Rota la IP o agrega el nombre de host a las reglas del proxy en tiempo de ejecución
Monitorear el uso	`account_get`, `account_usage`	Verifica el saldo y los datos consumidos
Automatización de múltiples sesiones	`session_start`, `session_close`, `session_list`	Nombra las sesiones mediante `browserSession`, gestiona varios navegadores

Ejemplo de prompt para el agente: "Abre target-site.com. Si te bloquean, rota la IP a una dirección de EE. UU. e inténtalo de nuevo."

→ El agente llama a session_start con autoUnblock: true, y luego a session_set_geo con geo: "us" si es necesario.

Por Qué Aluvia

IPs de operadores móviles — Las mismas IPs que usan los usuarios reales; los sitios confían en ellas
Detección de bloqueos — Detecta errores 403, desafíos WAF, CAPTCHAs; recarga automáticamente a través de Aluvia cuando se bloquea
Enrutamiento inteligente — Usa el proxy solo para los nombres de host que te bloquean; todo lo demás va directo (ahorra costos y latencia)
Orientación geográfica — Apunta a países (p. ej. us, gb, de) para contenido localizado
Actualizaciones en tiempo de ejecución — Agrega reglas, rota IPs, cambia la geolocalización sin reiniciar

Enlaces

Recurso	URL
Panel de Aluvia	dashboard.aluvia.io
npm	npmjs.com/package/@aluvia/mcp
Guía MCP Completa	docs/mcp-server-guide.md
SDK de Aluvia	@aluvia/sdk — CLI, adaptadores y inicio rápido
Protocolo MCP	modelcontextprotocol.io

Dependencias

@aluvia/sdk — Manejadores CLI y lógica de proxy. Para uso programático (AluviaClient, connect()), instala el SDK completo: npm install @aluvia/sdk.

Licencia

MIT