Bootleg-Link MCP

Daemon-style MCP server for YouTube music downloading with task queue, progress tracking, and concurrent download support.

Architecture

┌─────────────────────────────────────────────────────────┐
│                    OpenClaw                             │
│  ┌─────────────┐    ┌─────────────────────────────┐   │
│  │   Skill     │───►│   MCP Client (stdio bridge)  │   │
│  └─────────────┘    └──────────────┬──────────────┘   │
│                                    │                    │
│                         ┌──────────▼──────────┐        │
│                         │  bootleg-link-mcp   │        │
│                         │  ┌───────────────┐  │        │
│                         │  │  Task Queue   │  │        │
│                         │  │  (In-Memory)  │  │        │
│                         │  └───────┬───────┘  │        │
│                         │          │          │        │
│                         │  ┌───────▼───────┐  │        │
│                         │  │  Downloader   │  │        │
│                         │  │   (yt-dlp)    │  │        │
│                         │  └───────────────┘  │        │
│                         └─────────────────────┘        │
└─────────────────────────────────────────────────────────┘

MCP Tools

submit_download_task

Submit a new YouTube music download task.

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

Returns: taskId for tracking

query_progress

Query the progress of a download task.

{
  "taskId": "task_1234567890_abc123"
}

Returns:

{
  "taskId": "task_1234567890_abc123",
  "status": "downloading",
  "progress": 45,
  "message": "Downloading... 45%",
  "outputDir": "/path/to/output"
}

list_tasks

List all download tasks.

{
  "status": "all",
  "limit": 50
}

cancel_task

Cancel a pending or running task.

pause_task / resume_task

Pause or resume a downloading task.

clear_completed

Clear all completed/failed tasks.

Task States

| State | Description | |-------|-------------| | pending | Task created, waiting in queue | | downloading | Currently downloading | | completed | Download finished successfully | | failed | Download failed with error | | paused | Download paused by user | | cancelled | Download cancelled by user |

Configuration

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | BOOTLEG_OUTPUT_DIR | ~/Downloads/bootleg-link | Default output directory | | BOOTLEG_QUALITY | 320 | Default MP3 quality | | BOOTLEG_CONCURRENCY | 4 | Max concurrent downloads | | BOOTLEG_DB_PATH | ./tasks.db | SQLite database path |

Platform-Specific Paths

| OS | Default Output | |----|----------------| | Linux | ~/Downloads/bootleg-link | | macOS | ~/Downloads/bootleg-link | | Windows | %USERPROFILE%\Downloads\bootleg-link |

Installation

# Install dependencies
cd bootleg-link-mcp
npm install

# Build
npm run build

# Run
npm start

OpenClaw Configuration

Add to your OpenClaw MCP config:

{
  "mcpServers": {
    "bootleg-link": {
      "command": "node",
      "args": ["/path/to/bootleg-link-mcp/dist/server.js"],
      "env": {
        "BOOTLEG_OUTPUT_DIR": "/mnt/e/bootleg-link-downloader/output"
      }
    }
  }
}

Usage Example

// Submit a task
const result = await callTool('submit_download_task', {
  url: 'https://www.youtube.com/@VeryHouseMusic',
  quality: '320'
});
// Returns: { taskId: "task_xxx", status: "pending" }

// Query progress
const progress = await callTool('query_progress', {
  taskId: "task_xxx"
});
// Returns: { status: "downloading", progress: 45 }

// List all tasks
const tasks = await callTool('list_tasks', {
  status: 'downloading',
  limit: 10
});

Production vs Prototype

Prototype (Current)

• In-memory task storage
• Simulated download progress
• No real yt-dlp integration

Production (Planned)

• SQLite task persistence
• Real yt-dlp download with progress parsing
• Concurrent download management
• Event notification to OpenClaw
• Webhook notifications

Dependencies

• @modelcontextprotocol/sdk - MCP server framework
• yt-dlp-wrap - yt-dlp Node.js wrapper (future)
• better-sqlite3 - SQLite for task persistence (future)