yt-audio-mcp
Summary: This MCP server lets you search YouTube and download a video's audio as a tagged MP3, plus list what you've already downloaded.
Search YouTube (
search_youtube) — give a query like "artist - song title" and get back matching video IDs, titles, and URLs (1–25 results, default 5).Download a track as MP3 (
download_mp3) — pass a YouTube / YouTube Music / youtu.be link or a bare 11-character video ID and get the audio saved to/root/Music/yt-audio-mcp, with a choice of best-VBR (default) or fixed 320K/256K/192K/128K bitrates.Avoid re-downloading — already-downloaded videos are served from disk (reported as cached); set
force: trueto fetch again.List your library (
list_downloads) — see the MP3 files already saved, newest first.Chain them — search for a song, then feed the returned ID/URL straight into
download_mp3.
Note: only three tools are exposed (no video download or image generation here), and downloads are single tracks.
Downloads audio from YouTube videos and searches YouTube for tracks, converting results into tagged MP3 files with embedded cover art.
Downloads tracks from YouTube Music links as tagged MP3 files, with optional bitrate selection (up to 320 kbps) and search support.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@yt-audio-mcp download Daft Punk - One More Time as an MP3"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
📥 yt-download-mcp
Turn any YouTube or YouTube Music link into an MP3 or a video, right from your AI agent.
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.
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].mp4Quick 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#installationKeep 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 build3. 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 |
|
|
|
|
|
|
|
|
|
|
| MP3s and videos, newest first |
|
|
|
| same as | same as |
| 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>].mp3with ID3 tags and the cover art embedded.Videos too:
download_videosaves<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: trueto 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 |
|
| Where MP3s are saved |
|
| Where videos are saved |
|
| Path to the yt-dlp binary |
| none | Required for the image tools |
|
| Default image model |
|
| Where generated images are saved |
| 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> videodownloads the video (1080p MP4) instead.respect <song> 320downloads at 320 kbps.respect <link> againdownloads it again, even if you already have it.respect listshows 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 changePath | Purpose |
| MCP server and tool definitions |
| URL validation and the yt-dlp wrapper |
| OpenAI image tool definitions |
| OpenAI Images API client |
| Image model catalog and parameter checks |
| Unit tests |
| 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 toolsdownload_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 MP3sARead-only
List MP3 files already downloaded to /root/Music/yt-audio-mcp, newest first.
Inputs: no named parameters.
search_youtubeSearch YouTubeARead-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
Scored across 3 tools
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.
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.
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.
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
Related MCP Connectors
An MCP server that gives any LLM or agent clean YouTube transcripts on demand: a single video, a whole channel, or a playlist, plus AI cleanup of auto-generated captions. API-key auth, credit-based, same backend as the public v1 API. Get a free API key with 25 free credits at youtubetranscriptdownload.com/account.
MCP server for Producer/Riffusion AI music generation
An MCP server that gives your AI access to the source code and docs of all public github repos
Search and install 4,000+ security-scanned MCP servers from inside any MCP-aware AI client.
Related MCP Servers
- AlicenseBqualityDmaintenanceA simple MCP server that allows AI assistants like Cursor or Claude Desktop to search for and play tracks on YouTube Music through natural language commands.219 npm13MIT
- AlicenseNot gradedqualityNot gradedmaintenanceAn 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-
- AlicenseAqualityDmaintenanceMCP server that lets AI agents search YouTube and fetch transcripts.23MIT
- AlicenseNot gradedqualityCmaintenanceA comprehensive MCP server providing YouTube transcript retrieval, video search, channel browsing, playlist extraction, and upload monitoring for AI agents.13MIT