yoink-yt 0.1.2

MCP server that gives AI assistants YouTube download capabilities. Also ships with a terminal UI.

yoink

MCP server that lets AI assistants download YouTube videos.
_{Give Claude, Cursor, or any MCP-compatible AI the ability to download YouTube videos, playlists, and audio through natural language. Also ships with a terminal UI for humans.}

pip install yoink-yt  ·  MCP Setup  ·  Terminal UI  ·  API Reference

---

What is yoink?

yoink is an MCP (Model Context Protocol) server that gives AI assistants like Claude Desktop, Cursor, Windsurf, and other MCP-compatible tools the ability to download YouTube videos on your behalf.

It also ships with a standalone terminal UI (TUI) for when you want to download videos yourself.

The problem

Every YouTube downloader makes you do the work — find the URL, open a tool, pick a format, wait for it, rename the file, repeat.

The yoink way

Just tell your AI assistant what you want:

"Download the latest 3Blue1Brown video in 720p"

"Grab that playlist as audio-only MP3s"

"Download this lecture with subtitles to my Desktop"

Your AI handles the entire workflow — resolves the URL, picks the format, starts the download, tracks progress. No copy-pasting. No menus. Just ask.

⚡ Quick Start

pip install yoink-yt

For AI assistants (MCP server) yoink-mcp Add to Claude Desktop, Cursor, or any MCP client — your AI gets 7 YouTube tools instantly.

For humans (terminal UI) yoink A full terminal UI with progress bars, quality picker, playlist support, and keyboard shortcuts.

[!TIP] Install ffmpeg for best results — needed to merge video+audio streams and convert to MP3.

brew install ffmpeg          # macOS
sudo apt install ffmpeg      # Ubuntu/Debian

🤖 MCP Setup for AI Assistants

yoink exposes 7 tools via the Model Context Protocol over STDIO, giving any MCP-compatible AI assistant full YouTube download capabilities.

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "yoink": {
      "command": "yoink-mcp"
    }
  }
}

Restart Claude Desktop. Done — Claude can now download YouTube videos.

Claude Code

Add to your .mcp.json:

{
  "mcpServers": {
    "yoink": {
      "command": "yoink-mcp",
      "type": "stdio"
    }
  }
}

Cursor / Windsurf / Other MCP Clients

Any MCP client that supports STDIO transport works. Point it at yoink-mcp as the command.

Using uv (from source instead of pip)

{
  "mcpServers": {
    "yoink": {
      "command": "uv",
      "args": ["--directory", "/path/to/yoink", "run", "yoink-mcp"]
    }
  }
}

Example prompts for your AI

What you say	What yoink does
"Download this video: [url]"	Downloads in best quality to ~/Downloads
"Get the 720p version of [url]"	Fetches formats, picks 720p, downloads
"Download this playlist as audio"	Gets playlist info, downloads each as audio
"What formats are available for [url]?"	Lists all quality options with file sizes
"Cancel the download"	Stops an in-progress download
"What's the progress?"	Shows status of all active downloads
"Download [url] with subtitles"	Downloads video + subtitle files
"Convert [url] to MP3"	Downloads audio and converts to MP3

🔌 MCP Tools API Reference

These are the tools your AI assistant gets access to when yoink is configured as an MCP server:

Tool	Description	Key Parameters
get_video_info	Fetch video metadata (title, duration, uploader, available formats)	url
get_playlist_info	List all videos in a YouTube playlist	url
get_formats	List available download qualities with file sizes	url
start_download	Start downloading a video, returns a tracking ID	url, format_string, output_dir
list_downloads	Get progress of all active and completed downloads	—
get_download_progress	Check status of a specific download by ID	download_id
cancel_download	Cancel an active download	download_id

[!NOTE] Duplicate detection is built in — if a download is requested for a URL that's already being downloaded, yoink returns an error instead of starting a duplicate. This means your AI can safely retry without causing double-downloads.

🎬 Terminal UI for Humans

For when you want to download videos yourself. A full-featured TUI powered by Textual.

yoink              # default: 3 concurrent downloads
yoink -j 5         # up to 10

Keyboard shortcuts Key Action / Focus URL input d Start download r Retry last failed a Select all (playlist) n Select none (playlist) q Quit

Features Feature Details Quality picker 1080p down to audio-only Playlists Search, filter, batch download Audio-only One-click, or convert to MP3 Subtitles Auto-generated + manual subs Speed limit e.g. 5M for 5 MB/s cap Output dir Editable save path Retry One click on failed downloads Open folder One click on finished

🛠 Architecture

src/yoink/
├── core/              # Shared engine (used by both MCP + TUI)
│   ├── models.py      # Pydantic data models
│   ├── errors.py      # yt-dlp error → friendly message translation
│   ├── extractor.py   # YouTube metadata extraction via yt-dlp
│   ├── engine.py      # Single download executor with progress hooks
│   └── manager.py     # Concurrent download orchestration + duplicate detection
├── mcp_server/        # MCP interface for AI assistants
│   └── server.py      # FastMCP server with 7 tools over STDIO
└── tui/               # Terminal UI for humans
    ├── app.py         # Main Textual application
    ├── screens/       # Main screen, format picker modal
    ├── widgets/       # URL bar, video panel, playlist panel, download queue
    └── styles/        # Textual CSS styling

Both the MCP server and TUI are thin wrappers around the same core engine. The core handles all yt-dlp interaction, threading, progress tracking, and error handling.

Design decisions

• Threading model: yt-dlp is synchronous, so each download runs in its own thread via ThreadPoolExecutor. A FIFO dispatcher thread ensures downloads start in submission order.
• Progress reporting: Hooks are rate-limited to 100ms intervals to avoid callback floods in both MCP and TUI contexts.
• Playlist optimization: Uses extract_flat to avoid fetching full metadata for large playlists upfront.
• Error handling: Raw yt-dlp errors are pattern-matched against 15 common cases and translated to user-friendly messages.
• Duplicate detection: The download manager tracks active URLs and rejects duplicates at the engine level, with a force bypass for retries.
• Cancellation: Uses threading.Event checked in every progress hook callback for responsive cancellation.
• Data contracts: Pydantic models are shared across core, TUI, and MCP layers for type safety.

🔧 Development

git clone https://github.com/JayshKhan/yoink.git
cd yoink
uv sync --extra dev       # install with test deps
uv run pytest tests/ -v   # 84 tests
uv run yoink              # test the TUI
uv run yoink-mcp          # test the MCP server

Frequently Asked Questions

What AI assistants work with yoink?

Any AI assistant that supports the Model Context Protocol (MCP) over STDIO transport. This includes Claude Desktop, Claude Code, Cursor, Windsurf, and any custom MCP client.

Does it only work with YouTube?

yoink uses yt-dlp under the hood, which supports thousands of sites. However, yoink is optimized and tested for YouTube. Other sites may work but are not officially supported.

Can I use the MCP server and TUI at the same time?

They are separate processes with separate download managers, so yes. They won't share state or conflict with each other.

Where do downloads go?

By default, ~/Downloads. The MCP start_download tool accepts an output_dir parameter, and the TUI has an editable path below the URL bar.

What if ffmpeg is not installed?

You can still download videos, but some quality options that require merging separate video and audio streams won't work. MP3 conversion also requires ffmpeg.

📄 License

MIT — do whatever you want with it. Yoink responsibly.

_{Powered by yt-dlp · UI by Textual · AI integration via MCP}