youtube-downloader-mcp-server

SamuelBFavarin/youtube-downloader-mcp-server

3.2

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.

Tools
2
Resources
0
Prompts
0

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

  1. Clone the repository:

    git clone <your-repo-url>
    cd youtube-downloader-mcp
    
  2. Install Poetry (if you don't have it):

    pip install poetry
    
  3. Install dependencies:

    poetry install
    
  4. 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

  1. 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
  2. Claude will automatically discover the following tools:

    • download_youtube_video(url: str)
    • check_download_status(download_id: str)
  3. Example workflow: Claude YouTube Download Demo Claude YouTube Check Status Demo

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