youtube-dl-mcp

MCP server for downloading YouTube audio via yt-dlp. Runs over stdio, designed as a child server for mcp-proxy or any MCP-compatible host.

Tools

| Tool | Description | |------|-------------| | youtube_download_audio | Download audio from a YouTube video as MP3. | | youtube_get_video_info | Get video metadata (title, channel, duration, etc.) without downloading. |

Prerequisites

Both must be available in PATH:

• yt-dlp -- pip install yt-dlp
• ffmpeg -- used by yt-dlp for audio extraction

Install

npm install youtube-dl-mcp

Requires Node.js >= 18.

Configuration

No API keys required. Just needs yt-dlp and ffmpeg installed.

Usage

Standalone (stdio)

npx youtube-dl-mcp

MCP proxy config

{
  "youtube-dl-mcp": {
    "command": "node",
    "args": ["/path/to/youtube-dl-mcp/dist/index.js"]
  }
}

Claude Desktop config

{
  "mcpServers": {
    "youtube-dl": {
      "command": "npx",
      "args": ["youtube-dl-mcp"]
    }
  }
}

Tool Details

youtube_download_audio

Downloads audio and converts to MP3. Creates output directories recursively.

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | url | string | Yes | - | YouTube URL (youtube.com/watch?v=..., youtu.be/..., youtube.com/shorts/...) | | output_dir | string | No | /app/youtube-dl-output | Directory to save the MP3 | | filename | string | No | Sanitized video title | Custom filename (without .mp3 extension) | | audio_quality | string | No | 0 (best) | Quality from 0 (best) to 9 (worst) |

Returns: file_path, title, duration_seconds, file_size_bytes, channel.

Timeouts: Downloads time out after 300 seconds.

youtube_get_video_info

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | url | string | Yes | YouTube URL |

Returns: title, channel, duration_seconds, description (truncated to 500 chars), thumbnail_url, upload_date, view_count.

Timeouts: Info requests time out after 30 seconds.

Build

npm run build

License

MIT