vdl-mcp

MCP server for vdl — let AI assistants (Claude & co.) resolve, download and transcribe videos through your self-hosted vdl instance.

English · Deutsch

vdl-mcp connects an AI assistant to your own vdl server over the Model Context Protocol. The real power is the Whisper synergy:

Download → transcript → the assistant understands the content.

So you can say things like:

• "Download this YouTube video and summarize it."
• "Grab that cooking clip and write out the recipe as a list."
• "What was said about X in this interview?"
• "Download the audio of this talk and give me the key points."

It's a small stdio MCP server that talks to vdl's REST API and authenticates with your existing API token. Nothing runs inside vdl itself.

Tool groups are toggleable with safe defaults:

A disabled group is invisible to the assistant.

• A running vdl instance.
• An MCP token: in vdl open the MCP tab → create token and copy it. This token is scoped — it may only perform the MCP actions you enable there (write/delete tools respect the toggles and read-only mode, everything else is refused server-side), so it's safer than the general API token.

With pipx (puts vdl-mcp on your PATH):

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

or with uv:

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

Add this to your Claude Desktop config (claude_desktop_config.json):

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

Restart Claude Desktop — the vdl tools appear. (Any MCP-capable client works the same way; just run the vdl-mcp command over stdio.)

Prefer a container? A prebuilt image is published to GHCR — use it as the command:

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

Note the -i (keep stdin open for stdio) and, when vdl runs on the same host, host.docker.internal so the container can reach it.

vdl-mcp is a stdio process launched locally by your MCP client. It does not open a network port, so it has no login page and no fail2ban — there is nothing inbound to protect. Its security model is: keep your API token private, leave destructive tools off (the defaults), and optionally set a domain allowlist. Authentication and brute-force protection live in vdl itself. (If you ever want a remote, multi-client HTTP server instead, that's a different transport — open an issue.)

• resolve(url) — analyze a link, list items and available qualities (no download).
• download(url, audio=False, section="", wait=True) — download best quality (or MP3); section like 0:30-1:00 clips; wait returns the finished file name.
• transcribe(name, language="") — Whisper transcription → returns the text (requires a Whisper model set in vdl).
• get_transcript(name) — return an existing transcript's text.
• list_files(query, service, label, limit) — browse your downloads.
• job_status(job_id) — check a download job.
• (off by default) delete_file, bulk, get_settings.

Every tool is tagged in its description — [read], [writes] or [deletes] — so both you and the assistant can see its risk at a glance.

Manage it from vdl's web UI too: in vdl go to Settings → MCP tab to toggle each tool (with a read-only master switch and risk chips). vdl-mcp fetches that config at startup, so no env vars are needed — restart vdl-mcp after changes. Precedence for whether a tool is exposed: read-only (env or UI) → per-tool env override → web UI → group flag.

• The assistant acts as you via your token — keep it private.
• Destructive tools are off by default. Enable them consciously.
• Downloading an arbitrary URL on an assistant's request has a prompt-injection surface. Set VDL_MCP_DOMAIN_ALLOWLIST (e.g. youtube.com,instagram.com) to restrict it.
• Only for content you own or have the rights/permission to download — the same disclaimer as vdl applies.

These tools are built and maintained in my free time, and they stay free, open and cloud-free. If one of them saved you an afternoon, you can buy me a coffee.

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