vdl-mcp

vdl-mcp conecta un asistente de IA a tu propio servidor vdl a través del Model Context Protocol. El verdadero poder está en la sinergia con Whisper:

Descarga → transcripción → el asistente comprende el contenido.

Así que puedes decir cosas como:

• "Descarga este video de YouTube y resúmelo."

• "Toma ese clip de cocina y escribe la receta como una lista."

• "¿Qué se dijo sobre X en esta entrevista?"

• "Descarga el audio de esta charla y dame los puntos clave."

Cómo funciona

Es un pequeño servidor MCP stdio que se comunica con la API REST de vdl y se autentica con tu token de API existente. No se ejecuta nada dentro de vdl.

Los grupos de herramientas son activables con valores predeterminados seguros:

Un grupo desactivado es invisible para el asistente.

Related MCP server: popcorn

Requisitos

• Una instancia de vdl en ejecución.

• Un token MCP: en vdl abre la pestaña MCP → crea un token y cópialo. Este token tiene alcance limitado — solo puede realizar las acciones MCP que habilites allí (las herramientas de escritura/eliminación respetan las alternancias y el modo de solo lectura, todo lo demás es rechazado del lado del servidor), por lo que es más seguro que el token de API general.

Instalación

Con pipx (coloca vdl-mcp en tu PATH):

pipx install git+https://github.com/sphings79/vdl-mcp

o con uv:

uv tool install git+https://github.com/sphings79/vdl-mcp

Conéctalo a Claude Desktop

Añade esto a la configuración de Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "vdl": {
      "command": "vdl-mcp",
      "env": {
        "VDL_URL": "http://localhost:8000",
        "VDL_TOKEN": "your-api-token"
      }
    }
  }
}

Reinicia Claude Desktop — aparecen las herramientas de vdl. (Cualquier cliente compatible con MCP funciona de la misma manera; solo ejecuta el comando vdl-mcp a través de stdio).

Ejecutar con Docker

¿Prefieres un contenedor? Hay una imagen preconstruida publicada en GHCR — úsala como comando:

{
  "mcpServers": {
    "vdl": {
      "command": "docker",
      "args": ["run", "-i", "--rm",
               "-e", "VDL_URL", "-e", "VDL_TOKEN",
               "ghcr.io/sphings79/vdl-mcp:latest"],
      "env": {
        "VDL_URL": "http://host.docker.internal:8000",
        "VDL_TOKEN": "your-api-token"
      }
    }
  }
}

Nota la opción -i (mantener stdin abierto para stdio) y, cuando vdl se ejecute en el mismo host, host.docker.internal para que el contenedor pueda alcanzarlo.

Sin interfaz web — por diseño

vdl-mcp es un proceso stdio iniciado localmente por tu cliente MCP. No abre un puerto de red, por lo que no tiene página de inicio de sesión ni fail2ban — no hay nada entrante que proteger. Su modelo de seguridad es: mantén tu token de API privado, deja las herramientas destructivas desactivadas (los valores predeterminados) y, opcionalmente, establece una lista de dominios permitidos. La autenticación y la protección contra fuerza bruta residen en el propio vdl. (Si alguna vez deseas un servidor HTTP remoto para múltiples clientes, ese es un transporte diferente — abre un issue).

Herramientas

• resolve(url) — analiza un enlace, lista los elementos y las calidades disponibles (sin descarga).

• download(url, audio=False, section="", wait=True) — descarga la mejor calidad (o MP3); section como 0:30-1:00 recorta; wait devuelve el name del archivo finalizado.

• transcribe(name, language="") — transcripción con Whisper → devuelve el texto (requiere un modelo Whisper configurado en vdl).

• get_transcript(name) — devuelve el texto de una transcripción existente.

• list_files(query, service, label, limit) — navega por tus descargas.

• job_status(job_id) — verifica el estado de un trabajo de descarga.

• (desactivado por defecto) delete_file, bulk, get_settings.

Configuración (variables de entorno)

Cada herramienta está etiquetada en su descripción — [lectura], [escritura] o [eliminación] — para que tanto tú como el asistente puedan ver su riesgo de un vistazo.

Gestiona también desde la interfaz web de vdl: en vdl ve a Ajustes → pestaña MCP para activar o desactivar cada herramienta (con un interruptor maestro de solo lectura y chips de riesgo). vdl-mcp obtiene esa configuración al inicio, por lo que no se necesitan variables de entorno — reinicia vdl-mcp después de los cambios. Precedencia para determinar si una herramienta está expuesta: solo lectura (entorno o interfaz web) → anulación por herramienta en entorno → interfaz web → bandera de grupo.

Notas de seguridad

• El asistente actúa como tú a través de tu token — mantenlo privado.

• Las herramientas destructivas están desactivadas por defecto. Actívalas conscientemente.

• Descargar una URL arbitraria a petición de un asistente tiene una superficie de inyección de indicaciones. Establece VDL_MCP_DOMAIN_ALLOWLIST (ej. youtube.com,instagram.com) para restringirlo.

• Solo para contenido que poseas o para el que tengas los derechos/permiso de descarga — se aplica el mismo aviso legal que en vdl.

Licencia

GNU Affero General Public License v3.0 (AGPL-3.0) — consulta LICENSE. © 2026 sphings79