Ytmp3

A Model Context Protocol (MCP) server that lets your AI download YouTube audio and search videos — powered by yt-dlp and ffmpeg, shipped as a Docker image.

---

What it does

Tool	Description
download_audio	Downloads audio from any YouTube URL as MP3. Supports time-range clipping.
search_videos	Searches YouTube and returns titles, channels, durations, and URLs.

More tools coming soon.

---

Requirements

• Docker Desktop — for Docker usage
• Node.js 18+ — for running directly via npm/npx
• yt-dlp and ffmpeg installed on your system — for npm usage

---

Important

If you want playlist download, keep the below as 'system prompt'

When a tool returns a list of video URLs, you MUST immediately call download_audio for each URL one by one without asking for confirmation or summarizing. Do not stop until every URL has been passed to download_audio.

Docker (recommended, no setup)

1. Pull the image

docker pull piyush9969/ytmp3-mcp:latest

2. Add to your MCP client config

{
  "mcpServers": {
    "ytmp3-mcp": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "/Users/yourname/Downloads:/downloads",
        "-e", "DOWNLOADS_DIR=/downloads",
        "piyush9969/ytmp3-mcp:latest"
      ]
    }
  }
}

Update the volume path for your OS:

OS	Volume path
Mac	/Users/yourname/Downloads:/downloads
Linux	/home/yourname/Downloads:/downloads
Windows	C:/Users/yourname/Downloads:/downloads

---

Build from source (Docker)

If you want to build the image yourself instead of pulling:

git clone https://github.com/miteoshi/ytmp3-mcp.git
cd ytmp3-mcp
docker build -t ytmp3-mcp .

Then use the same mcp.json as above but replace the image name:

{
  "mcpServers": {
    "ytmp3-mcp": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "/Users/yourname/Downloads:/downloads",
        "-e", "DOWNLOADS_DIR=/downloads",
        "ytmp3-mcp"
      ]
    }
  }
}

---

Run directly via npm (no Docker)

Requires yt-dlp and ffmpeg installed on your machine:

Mac:

brew install yt-dlp ffmpeg

Windows:

winget install yt-dlp ffmpeg

Linux:

sudo apt install ffmpeg
pip install yt-dlp

Then clone and install:

git clone https://github.com/miteoshi/ytmp3-mcp.git
cd ytmp3-mcp
npm install

Add to your MCP client config:

{
  "mcpServers": {
    "ytmp3-mcp": {
      "command": "npx",
      "args": [
        "tsx",
        "/path/to/ytmp3-mcp/src/index.mts"
      ]
    }
  }
}

Replace /path/to/ytmp3-mcp with the actual path where you cloned the repo.

---

LM Studio config location

Settings → LLM → MCP Servers → Edit config

---

Usage

Once connected, just talk to your LLM naturally:

Download the audio from https://www.youtube.com/watch?v=...

Download only 1:00 to 2:30 from https://www.youtube.com/watch?v=...

Search YouTube for "baby keem new music"

Downloaded files appear in your ~/Downloads folder, named after the video title.

Supported time formats for clipping

Format	Example
MM:SS	1:30
HH:MM:SS	00:01:30
Seconds	90s

---

How it works

LLM client
    └── MCP call
            └── docker run  (or npx tsx)
                    └── yt-dlp + ffmpeg
                            └── ~/Downloads

Each tool call spawns a fresh process, runs the command, and exits. No persistent container, no background process.

---

adding more features..