vdl-mcp – MCP-Server für Videos und Whisper-Transkripte

vdl-mcp verbindet einen KI-Assistenten über das Model Context Protocol mit einer selbst gehosteten vdl-Instanz. Der Assistent kann Links analysieren, Videos oder Audio herunterladen, Downloads durchsuchen und, wenn vdl ein Whisper-Modell hat, den Ton transkribieren lassen. Daraus ergibt sich der Kern des Projekts: Download, Transkript, und der Assistent kann den Inhalt zusammenfassen oder daraus Fragen beantworten. vdl-mcp ist in Python geschrieben (fastmcp, httpx) und steht unter der AGPL-3.0.

Aufbau

Es ist ein kleiner stdio-MCP-Server, den der MCP-Client lokal startet. Er spricht mit der REST-API von vdl und meldet sich mit einem Token an; in vdl selbst läuft nichts Zusätzliches. Weil er keinen Netzwerk-Port öffnet, gibt es keine Login-Seite, die zu schützen wäre. Anmeldung und Schutz vor Brute-Force liegen in vdl. Ein HTTP-Transport für mehrere Clients ist nicht vorhanden; in diesem Fall bitte ich um ein Issue.

Werkzeuge

resolve(url): einen Link analysieren, Items und Qualitäten anzeigen, ohne zu laden.
download(url, audio, section, wait): in bester Qualität oder als MP3 laden, mit section (zum Beispiel 0:30-1:00) zuschneiden; mit wait kommt der Dateiname des fertigen Downloads zurück.
transcribe(name, language) und get_transcript(name): Whisper-Transkription auslösen bzw. den Text eines vorhandenen Transkripts holen.
list_files(query, service, label, limit) und job_status(job_id): Downloads durchsuchen, einen Job prüfen.
Standardmäßig aus: delete_file, bulk und get_settings.

Die Werkzeuge sind in Gruppen schaltbar (Lesen, Download, Transkribieren an; Löschen, Massenaktion, Einstellungen aus). Eine deaktivierte Gruppe ist für den Assistenten unsichtbar. Dazu gibt es einen Nur-Lesen-Notschalter, Pro-Tool-Overrides über Umgebungsvariablen wie VDL_MCP_TOOL_download=off und eine Domain-Allowlist (VDL_MCP_DOMAIN_ALLOWLIST, zum Beispiel youtube.com), die einschränkt, von welchen Hosts der Assistent laden darf. Jedes Werkzeug ist in seiner Beschreibung als [read], [writes] oder [deletes] gekennzeichnet. Die Schalter lassen sich auch in vdl unter „Einstellungen → MCP“ setzen; vdl-mcp holt diese Konfiguration beim Start.

Einbinden

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

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

Statt pipx geht auch uv tool install, außerdem gibt es ein Image unter ghcr.io/sphings79/vdl-mcp:latest, das mit docker run -i --rm als Befehl eingetragen wird (bei vdl auf demselben Host mit host.docker.internal). Das Token erzeugt man in vdl im Reiter „MCP“; es ist auf die dort aktivierten MCP-Aktionen beschränkt und deshalb sicherer als das allgemeine API-Token. Voraussetzung sind eine laufende vdl-Instanz und Python 3.10 oder neuer.

Sicherheit

Der Assistent handelt über das Token als der Nutzer selbst. Eine beliebige URL auf Zuruf des Assistenten zu laden, hat eine Prompt-Injection-Fläche, deshalb empfehle ich die Domain-Allowlist. Heruntergeladen werden sollten nur Inhalte, die einem gehören oder für die man die Rechte hat; es gilt derselbe Haftungsausschluss wie bei vdl.

Steckbrief

Aufbau

Werkzeuge

Einbinden

Sicherheit