SamuelBFavarin/youtube-downloader-mcp-server
If you are the rightful owner of youtube-downloader-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.
The YouTube Downloader MCP Server is a Multi-Channel Protocol server that enables AI agents like Claude to download YouTube videos directly to a computer's Downloads folder.
YouTube Downloader MCP Server 📺
This project is an MCP (Multi-Channel Protocol) server that allows Claude (or any MCP-compatible AI agent) to download YouTube videos directly to your computer's Downloads folder. It is designed for seamless integration with Claude's tool-calling capabilities.
Features
- Exposes two MCP tools:
download_youtube_video(url: str)
: Starts a YouTube video download in the background and returns a download ID.check_download_status(download_id: str)
: Lets you check the status of a download (in progress, completed, or error).
- Downloads are saved to your system's Downloads folder.
- Fully async/background operation.
Installation
-
Clone the repository:
git clone <your-repo-url> cd youtube-downloader-mcp
-
Install Poetry (if you don't have it):
pip install poetry
-
Install dependencies:
poetry install
-
Install FFmpeg
Check and follow the instructions to install this tool using this website (https://ffmpeg.org/). The
yt_dlp
needs FFmpeg to merge the audio and video files into a single mp4 file.
Running the MCP Server
Run the server using Poetry:
poetry run python endpoints.py
You should see a message like:
Running YouTube Downloader MCP server
Using with Claude
-
Add this server as a tool in Claude's settings (or use the Claude desktop app's "Add MCP server" feature).
- Update your
claude_desktop_config.json
adding this MCP Server configuration: -
{ "mcpServers": { "youtube-dowloader": { "command": "poetry", "args": [ "--directory", "<your_project_path>", "run", "python", "endpoints.py" ] } } }
- For more info, please check this link https://modelcontextprotocol.io/quickstart/user
- Update your
-
Claude will automatically discover the following tools:
download_youtube_video(url: str)
check_download_status(download_id: str)
-
Example workflow:
Running Tests
To run the unit tests for the YoutubeDownloader service, use:
poetry run python -m unittest tests/test_services.py
All tests are located in the tests/
directory. These tests use mocks, so no real downloads or system calls are made.
Notes
- FFmpeg is required for video merging. If you don't have it, download from ffmpeg.org and ensure it's in your PATH.
- All downloads go to your system's Downloads folder.
- This server is designed for use with Claude, but any MCP-compatible client can use it.
Troubleshooting
- If you see errors about non-JSON output, make sure you are running the latest code (all yt-dlp logs are redirected to stderr).
- If you get
ffmpeg not installed
errors, install FFmpeg and restart the server. - If you have issues with status not updating, ensure only one server instance is running at a time.
License
MIT