MCP & Tools¶

VDL integrates with Claude Desktop and other MCP clients through an MCP server, and provides stateless tool functions for integration.

What is MCP?¶

The Model Context Protocol (MCP) allows Claude (or other AI agents) to call tools exposed by a local or remote server. VDL exposes five tools for downloading, planning, resolving playlists, checking status, and health checks.

Installation¶

Install VDL with MCP support:

# Binary
curl -fsSL https://bildcraft.gitlab.io/products/video-downloader/vdl/install.sh | sh

# Or pip
pip install "vdl[mcp]"

Claude Desktop Setup¶

1. Generate Config¶

vdl mcp setup

This outputs JSON snippets for claude_desktop_config.json.

2. Add to Configuration¶

Edit ~/.config/Claude/claude_desktop_config.json (macOS/Linux) or the Windows equivalent:

{
  "mcpServers": {
    "vdl": {
      "command": "vdl-mcp",
      "disabled": false
    }
  }
}

Or if vdl-mcp is not on PATH:

{
  "mcpServers": {
    "vdl": {
      "command": "python",
      "args": ["-m", "vdl.mcp_server"]
    }
  }
}

3. Restart Claude¶

Close and reopen Claude Desktop. The VDL tools should appear in the tool list.

Running the MCP Server Directly¶

vdl-mcp

This starts the server on stdio transport (used by Claude).

MCP Tools¶

Five tools are exposed by the VDL MCP server:

`vdl_download_video`¶

Download a single video.

Parameters: - url (required): Video URL - quality (required): Quality level (best, 720p, 1080p, audio, etc.) - output_dir (required): Where to save the file - if_exists (optional): Collision policy (rename, skip, overwrite, fail) - write_thumbnail (optional): Write thumbnail sidecar - write_subtitles (optional): Write subtitle files - subtitle_langs (optional): Comma-separated language codes

Returns: JSON with status, output_path, error, etc.

`vdl_plan_download`¶

Build a download plan without executing.

Parameters: - url (required): Input URL or file path - quality (optional): Quality preference - output_dir (optional): Output directory - write_thumbnail (optional) - write_subtitles (optional) - subtitle_langs (optional)

Note: Does NOT have if_exists — planning is policy-neutral.

Returns: JSON plan with items, total, kind, metadata

`vdl_resolve_playlist`¶

List playlist items without downloading.

Parameters: - url (required): Playlist URL

Returns: JSON with title, items (array of { index, title, url, duration })

`vdl_get_status`¶

Query download history.

Parameters: - id (optional): Specific download ID

Returns: Single record (with id) or list of recent records (without id), or null

`vdl_doctor`¶

Health check.

Parameters: None

Returns: JSON report with tool availability and versions

vdl.tools — Python Functions¶

For Python-based integrations (not MCP):

from vdl.tools import download_video, resolve_playlist, doctor

# Async version
result = await download_video(
    url="https://example.com/video",
    quality="720p",
    output_dir="~/Videos",
    if_exists="rename",
    client=client
)

# Sync version (calls asyncio.run internally)
result = download_video_sync(url="...", client=client)

Available functions: - download_video() / download_video_sync() - plan_download() / plan_download_sync() - resolve_playlist() / resolve_playlist_sync() - get_status() / get_status_sync() - doctor() / doctor_sync()

All functions return JSON-serializable dicts.

Runtime Wiring¶

The MCP server uses a stateless VDLClient:

# vdl/mcp_server.py
client = build_default_client()  # No SQLite, no file logging

This means: - Downloads are not recorded to history (use interactive mode for persistent state) - No app directories are created - Safe for headless/automated use

Tool Output Format¶

All tools return JSON. Example:

{
  "id": "download-abc123",
  "source_url": "https://example.com/video",
  "status": "completed",
  "quality": "720p",
  "output_path": "/home/user/Downloads/VDL/video.mp4",
  "error": null,
  "skip_reason": null,
  "metadata": {
    "duration": 180,
    "format": "mp4"
  }
}

Integration Example¶

In Claude, you can ask:

"Download a video from https://example.com/video at 720p to ~/Videos"

Claude will call vdl_download_video with appropriate parameters and report the result.

Or:

"List the videos in this playlist: https://example.com/playlist"

Claude will call vdl_resolve_playlist and show you the items.