Bootleg-Link MCP

MCP server for downloading YouTube audio as MP3 with embedded cover art, task queue, progress tracking, and SQLite persistence

Bootleg-Link MCP v0.7.0

Python MCP server for downloading YouTube audio as MP3 with automatic cover art embedding. Features a task queue, concurrent download manager, SQLite-based persistence, and paged playlist support.

Architecture

Single-file Python MCP server (src/server.py) communicating over stdin/stdout via JSON-RPC 2.0.

• Task Queue: In-memory queue with SQLite persistence for resume across restarts
• Download Engine: yt-dlp Python API with bestaudio/best format
• Cover Art: Downloads thumbnail via writethumbnail, embeds into MP3 ID3 APIC frame using mutagen, then cleans up webp/webm files
• Concurrency: ThreadPoolExecutor with configurable worker count
• Paged Playlist: Flat playlist extraction (100 per page) for large channel downloads

MCP Tools

Tool	Description
submit_download_task	Submit a YouTube URL/channel for audio download
query_progress	Query task progress and status
list_tasks	List all tasks with optional status filter
cancel_task	Cancel a pending or running task
clear_completed	Clear completed/failed/cancelled tasks
get_queue_status	Get queue metrics (active, queued, total)

submit_download_task

{
  "url": "https://www.youtube.com/@ChannelName/videos",
  "quality": "320",
  "outputDir": "/path/to/output"
}

Returns: { "success": true, "taskId": "task_xxx", "status": "pending" }

query_progress

{
  "taskId": "task_xxx"
}

Returns: { "status": "downloading", "progress": 45, "songsCompleted": 5, "songsTotal": 100 }

Dependencies

• yt-dlp — YouTube audio extraction
• mutagen — MP3 ID3 tag manipulation and cover art embedding
• Python 3.10+ (stdlib only: sqlite3, json, threading, concurrent.futures)

Installation

pip install yt-dlp mutagen

Configuration

Config file: ~/.bootleg-link-mcp/config.json

{
  "paths": {
    "outputDir": "~/Downloads/bootleg-link",
    "dbPath": "~/.bootleg-link-mcp/bootleg-link.db"
  },
  "proxy": {
    "http": "http://proxy:port",
    "https": "http://proxy:port"
  },
  "download": {
    "maxConcurrent": 4,
    "quality": "320"
  }
}

Or via OpenClaw MCP config with environment variables (deprecated, use config.json):

{
  "command": "/path/to/python3",
  "args": ["src/server.py"],
  "env": {
    "BOOTLEG_OUTPUT_DIR": "/mnt/e/downloads",
    "BOOTLEG_HTTP_PROXY": "http://proxy:1081",
    "BOOTLEG_HTTPS_PROXY": "http://proxy:1081"
  }
}

Development

# Run tests (67 test cases)
/opt/pyenv/versions/3.11.8/bin/python3 test_mcp.py

# Run server directly
/opt/pyenv/versions/3.11.8/bin/python3 src/server.py