Skip to main content
Glama

📥 yt-download-mcp

Ask "download Daft Punk – One More Time as an MP3" and get a tagged file with cover art in your Music folder. Ask for the video and get a 1080p MP4.

CI MIT license MCP server Node.js 20+ PRs welcome GitHub stars

Quick start · Tools · Clients · The "respect" shortcut · FAQ · Contributing


yt-download-mcp is a small Model Context Protocol server that gives Claude Code, Claude Desktop, Cursor or any other MCP client four tools: search YouTube, download a track as MP3, download a video, and list what you already have.

Under the hood it runs yt-dlp and ffmpeg, which keep working as YouTube changes. Everything runs on your machine; no API keys, no accounts, no cloud.

You:    respect daft punk one more time
Claude: Daft Punk - One More Time (Official Video), 5:21
        → ~/Music/yt-download-mcp/Daft Punk - One More Time (Official Video) [FGBhQbmPwH8].mp3

You:    download the video of that in 720p
Claude: → ~/Music/yt-download-mcp/video/Daft Punk - One More Time (Official Video) [FGBhQbmPwH8].mp4

Quick start

1. Install yt-dlp and ffmpeg

brew install yt-dlp ffmpeg        # macOS
# Linux: install ffmpeg from your package manager and yt-dlp from https://github.com/yt-dlp/yt-dlp#installation

Keep yt-dlp current (brew upgrade yt-dlp), since YouTube changes often.

2. Build the server

git clone https://github.com/DaniilPak/yt-download-mcp.git
cd yt-download-mcp
npm install && npm run build

3. Add it to Claude Code

claude mcp add yt-download --scope user -e YT_AUDIO_DIR=~/Music/yt-download-mcp -- node "$PWD/dist/index.js"

Start a new Claude Code session and ask it to download a song or a video.

Related MCP server: yt

Tools

Tool

Input

Returns

download_mp3

url (youtube.com, music.youtube.com, youtu.be, or an 11-character video ID), bitrate ("0" best VBR by default, or 320K / 256K / 192K / 128K), force

{ id, title, duration, uploader, filepath, cached }

download_video

url, quality ("1080" by default, or best / 2160 / 1440 / 720 / 480 / 360), container (mp4 by default, or mkv / webm), force

{ id, title, duration, uploader, height, filepath, cached }

search_youtube

query, limit (1–25, default 5)

[{ id, title, duration, channel, url }]

list_downloads

type (all by default, or audio / video)

MP3s and videos, newest first

generate_image

prompt, model (default gpt-image-2.5-flare), size, quality, background, output_format, n, output_dir, include_images

{ model, files: [{ path, bytes }], usage }

edit_image

same as generate_image, plus images (1–16 paths / URLs / file IDs), mask, input_fidelity

same as generate_image

list_image_models

none

OpenAI image models and their capabilities

The image tools call the OpenAI Images API and need OPENAI_API_KEY; the YouTube tools work without it.

  • Tagged files: saved as <title> [<videoId>].mp3 with ID3 tags and the cover art embedded.

  • Videos too: download_video saves <title> [<videoId>].mp4 (H.264/AAC preferred so it plays in QuickTime and on iOS; VP9/AV1 only when the resolution needs it) with metadata, chapters and the thumbnail embedded. If the requested resolution doesn't exist, the next lower one is used.

  • No duplicates: a video you already downloaded is returned from disk. Pass force: true to download it again.

  • Single tracks only: playlist parameters (&list=…) are dropped.

  • Safe input: only YouTube hosts are accepted, and yt-dlp is called without a shell.

Connect your client

Claude Desktop

Add this to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows), with the path to your clone:

{
  "mcpServers": {
    "yt-download": {
      "command": "node",
      "args": ["/path/to/yt-download-mcp/dist/index.js"],
      "env": { "YT_AUDIO_DIR": "~/Music/yt-download-mcp" }
    }
  }
}

Cursor and other MCP clients

Any client that supports stdio MCP servers works. Use node /path/to/yt-download-mcp/dist/index.js as the command and set the environment variables below if you need them.

Environment

Variable

Default

Purpose

YT_AUDIO_DIR

~/Music/yt-download-mcp

Where MP3s are saved

YT_VIDEO_DIR

<YT_AUDIO_DIR>/video

Where videos are saved

YTDLP_PATH

yt-dlp (from PATH)

Path to the yt-dlp binary

OPENAI_API_KEY

none

Required for the image tools

OPENAI_IMAGE_MODEL

gpt-image-2.5-flare

Default image model

OPENAI_IMAGE_OUTPUT_DIR

~/Pictures/openai-image-mcp

Where generated images are saved

OPENAI_BASE_URL, OPENAI_ORG_ID, OPENAI_PROJECT_ID, OPENAI_IMAGE_TIMEOUT_MS

Optional OpenAI API settings

Desktop apps often don't inherit your shell's PATH. If you see "yt-dlp not found", set YTDLP_PATH=/opt/homebrew/bin/yt-dlp. If ffmpeg isn't found either, add "PATH": "/opt/homebrew/bin:/usr/bin:/bin" to the env block.

The "respect" shortcut

The repo includes a Claude Code skill in skills/respect. Copy it to your skills folder:

mkdir -p ~/.claude/skills && cp -r skills/respect ~/.claude/skills/

Then type respect <link | video id | song name> (or /respect …) in Claude Code and it downloads the MP3 right away. A few extras:

  • respect <link | song> video downloads the video (1080p MP4) instead.

  • respect <song> 320 downloads at 320 kbps.

  • respect <link> again downloads it again, even if you already have it.

  • respect list shows what you've downloaded.

FAQ

Why yt-dlp and not a JavaScript library? JavaScript YouTube libraries break whenever YouTube changes its player, and often produce empty files. yt-dlp is actively maintained and fixes these within days.

Does it work on Windows and Linux? The server is plain Node.js and runs anywhere yt-dlp and ffmpeg do. The examples use macOS paths; adjust them for your system.

Can it download whole playlists? Not yet: it downloads one track per call and drops playlist parameters. Playlist support would make a good contribution.

Can it download video, not just audio? Yes. download_video saves an MP4 (or MKV / WebM) at up to the resolution you ask for, 1080p by default and up to 4K.

Where do my files go? MP3s go to ~/Music/yt-download-mcp (or YT_AUDIO_DIR), videos to its video subfolder (or YT_VIDEO_DIR).

Development

npm install
npm test          # builds, then runs the unit tests in src/*.test.ts
npm run dev       # rebuild on change

Path

Purpose

src/index.ts

MCP server and tool definitions

src/ytdlp.ts

URL validation and the yt-dlp wrapper

src/images.ts

OpenAI image tool definitions

src/openai.ts

OpenAI Images API client

src/models.ts

Image model catalog and parameter checks

src/*.test.ts

Unit tests

skills/respect

The "respect" Claude Code skill

Contributing

Bug reports and pull requests are welcome. See CONTRIBUTING.md, or pick an issue labeled good first issue.

If yt-download-mcp is useful to you, a ⭐ helps other people find it.

Disclaimer

This tool is for downloading content you have the right to download, such as your own uploads, Creative Commons or public-domain audio and video, or content whose owner allows it. Respect copyright and YouTube's Terms of Service. The authors are not responsible for how the tool is used.

License

MIT © Daniil Pak

Available Tools

3 tools
download_mp3Download MP3 from YouTubeA

Download the audio of a YouTube or YouTube Music video as an MP3 file. Files are saved to /root/Music/yt-audio-mcp. Already-downloaded videos are returned from disk unless force=true.

Inputs: url (required), force, bitrate.

list_downloadsList downloaded MP3sA
Read-only

List MP3 files already downloaded to /root/Music/yt-audio-mcp, newest first.

Inputs: no named parameters.

search_youtubeSearch YouTubeA
Read-only

Search YouTube and return video IDs/URLs that can be passed to download_mp3.

Inputs: query (required), limit.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 3 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: search_youtube finds videos, download_mp3 fetches audio, list_downloads inspects the local library. No overlap or ambiguity exists between them.

    Naming Consistency4/5

    All three follow a verb_noun pattern (search_youtube, download_mp3, list_downloads), which is mostly consistent. The only minor deviation is download_mp3 using a file format (mp3) as the noun rather than a resource like 'audio', but the pattern is still readable and predictable.

    Tool Count5/5

    Three tools is well-scoped for a focused YouTube-audio downloader. Each tool earns its place and covers a distinct step in the workflow without bloat.

    Completeness4/5

    The core workflow (search, download, list) is fully covered. Minor gaps exist—no delete/remove downloaded files and no explicit overwrite/force management beyond the description note—but agents can work around these.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      An MCP server that provides YouTube data access without API keys or quotas. It enables agents to search videos, retrieve transcripts and metadata, and perform full-text search across cached content for AI context retrieval.
      3 npm
      -