vdl-mcp

vdl-mcp verbindet einen KI-Assistenten mit Ihrem eigenen vdl-Server über das Model Context Protocol. Die wahre Stärke liegt in der Whisper-Synergie:

Download → Transkript → der Assistent versteht den Inhalt.

So können Sie Dinge sagen wie:

• "Laden Sie dieses YouTube-Video herunter und fassen Sie es zusammen."

• "Nehmen Sie diesen Kochclip und schreiben Sie das Rezept als Liste auf."

• "Was wurde in diesem Interview über X gesagt?"

• "Laden Sie das Audio dieses Vortrags herunter und geben Sie mir die wichtigsten Punkte."

So funktioniert es

Es ist ein kleiner stdio MCP-Server, der mit der REST-API von vdl kommuniziert und sich mit Ihrem vorhandenen API-Token authentifiziert. Nichts läuft innerhalb von vdl selbst.

Tool-Gruppen sind umschaltbar mit sicheren Standardeinstellungen:

Eine deaktivierte Gruppe ist für den Assistenten unsichtbar.

Related MCP server: popcorn

Voraussetzungen

• Eine laufende vdl-Instanz.

• Ein MCP-Token: Öffnen Sie in vdl den MCP-Tab → Token erstellen und kopieren Sie ihn. Dieser Token ist eingeschränkt — er kann nur die MCP-Aktionen ausführen, die Sie dort aktivieren (Schreib-/Löschwerkzeuge respektieren die Umschalter und den Nur-Lesen-Modus, alles andere wird serverseitig abgelehnt), daher ist er sicherer als der allgemeine API-Token.

Installation

Mit pipx (setzt vdl-mcp in Ihren PATH):

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

oder mit uv:

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

Mit Claude Desktop verbinden

Fügen Sie dies zu Ihrer Claude Desktop-Konfiguration hinzu (claude_desktop_config.json):

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

Starten Sie Claude Desktop neu — die vdl-Werkzeuge erscheinen. (Jeder MCP-fähige Client funktioniert auf die gleiche Weise; führen Sie einfach den Befehl vdl-mcp über stdio aus.)

Mit Docker ausführen

Bevorzugen Sie einen Container? Ein vorgefertigtes Image wird auf GHCR veröffentlicht — verwenden Sie es als Befehl:

{
  "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"
      }
    }
  }
}

Beachten Sie das -i (hält stdin für stdio offen) und, wenn vdl auf demselben Host läuft, host.docker.internal, damit der Container es erreichen kann.

Keine Weboberfläche — bewusst so

vdl-mcp ist ein stdio-Prozess, der lokal von Ihrem MCP-Client gestartet wird. Es öffnet keinen Netzwerkport, hat daher keine Anmeldeseite und kein fail2ban — es gibt nichts eingehendes zu schützen. Sein Sicherheitsmodell ist: Halten Sie Ihren API-Token privat, lassen Sie destruktive Werkzeuge deaktiviert (die Standardeinstellungen) und legen Sie optional eine Domain-Whitelist fest. Authentifizierung und Brute-Force-Schutz liegen in vdl selbst. (Falls Sie stattdessen einen entfernten, Multi-Client-HTTP-Server wünschen, ist das ein anderer Transport — eröffnen Sie ein Issue.)

Werkzeuge

• resolve(url) — analysiert einen Link, listet Elemente und verfügbare Qualitäten auf (kein Download).

• download(url, audio=False, section="", wait=True) — lädt die beste Qualität (oder MP3) herunter; section wie 0:30-1:00 Ausschnitte; wait gibt den fertigen Dateinamen name zurück.

• transcribe(name, language="") — Whisper-Transkription → gibt den Text zurück (erfordert ein in vdl eingestelltes Whisper-Modell).

• get_transcript(name) — gibt den Text eines vorhandenen Transkripts zurück.

• list_files(query, service, label, limit) — durchsucht Ihre Downloads.

• job_status(job_id) — überprüft einen Download-Job.

• (standardmäßig deaktiviert) delete_file, bulk, get_settings.

Konfiguration (Umgebungsvariablen)

Jedes Werkzeug ist in seiner Beschreibung gekennzeichnet — [read], [writes] oder [deletes] — damit sowohl Sie als auch der Assistent das Risiko auf einen Blick erkennen können.

Verwalten Sie es auch über die Weboberfläche von vdl: Gehen Sie in vdl zu Einstellungen → MCP-Tab, um jedes Werkzeug umzuschalten (mit einem Nur-Lesen-Master-Schalter und Risiko-Chips). vdl-mcp ruft diese Konfiguration beim Start ab, daher sind keine Umgebungsvariablen erforderlich — starten Sie vdl-mcp nach Änderungen neu. Priorität dafür, ob ein Werkzeug bereitgestellt wird: Nur-Lesen (env oder UI) → Pro-Werkzeug-env-Überschreibung → Web-UI → Gruppen-Flag.

Sicherheitshinweise

• Der Assistent handelt als Sie über Ihren Token — halten Sie ihn privat.

• Destruktive Werkzeuge sind standardmäßig deaktiviert. Aktivieren Sie sie bewusst.

• Das Herunterladen einer beliebigen URL auf Anfrage eines Assistenten hat eine Prompt-Injection-Oberfläche. Setzen Sie VDL_MCP_DOMAIN_ALLOWLIST (z.B. youtube.com,instagram.com), um dies einzuschränken.

• Nur für Inhalte, die Sie besitzen oder für die Sie die Rechte/Erlaubnis zum Herunterladen haben — es gilt der gleiche Haftungsausschluss wie für vdl.

Lizenz

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