MCP 服务器

vdl-mcp

MCP server for vdl that lets AI assistants resolve, download, and transcribe videos through a self-hosted vdl instance.

README

MCP server for <a href="https://github.com/sphings79/vdl">vdl</a> — let AI assistants (Claude & co.) resolve, download and transcribe videos through your self-hosted vdl instance.

English · <a href="README.de.md">Deutsch</a>

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."

How it works

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:

Group	Tools	Default
Read	`resolve`, `list_files`, `job_status`, `get_transcript`	✅ on
Download	`download`	✅ on
Transcribe	`transcribe`	✅ on
Delete	`delete_file`	❌ off
Bulk	`bulk`	❌ off
Settings	`get_settings`	❌ off

A disabled group is invisible to the assistant.

Requirements

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.

Install

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

Connect it to Claude Desktop

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.)

Run with Docker

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.

No web UI — by design

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.)

Tools

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.

Configuration (environment variables)

Variable	Default	Meaning
`VDL_URL`	`http://localhost:8000`	Base URL of your vdl instance
`VDL_TOKEN`	(empty)	vdl MCP token (from the MCP tab)
`VDL_MCP_READ_ONLY`	`false`	Kill switch: expose only read tools (no download/transcribe/delete/bulk)
`VDL_MCP_ALLOW_READ`	`true`	resolve/list/status/get_transcript
`VDL_MCP_ALLOW_DOWNLOAD`	`true`	download
`VDL_MCP_ALLOW_TRANSCRIBE`	`true`	transcribe
`VDL_MCP_ALLOW_DELETE`	`false`	delete files
`VDL_MCP_ALLOW_BULK`	`false`	bulk actions
`VDL_MCP_ALLOW_SETTINGS`	`false`	read settings
`VDL_MCP_TOOL_<name>`	(unset)	Per-tool override, e.g. `VDL_MCP_TOOL_download=off` — beats the group flag
`VDL_MCP_DOMAIN_ALLOWLIST`	(empty = any)	comma-separated host suffixes the assistant may download from
`VDL_MCP_TIMEOUT`	`30`	default request timeout (seconds)

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.

Security notes

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.