fetch_transcript is free and fails with NO_CAPTIONS, and that specific error is where transcribe_video is documented as the next move; the transcription costs 5 credits and debits only on success, while polling its progress with get_asr_task costs nothing at all. The recommended polling interval is stated as 3-5 seconds, so an agent does not have to guess at it. Discovery is split by situation rather than by object — topic search when no channel is known, in-channel search when one is, the paginated listing for a back catalogue and the shortcut for recent uploads — which usually settles the choice of tool before you make it.
A YouTube research client: search and channel discovery, video metadata, official transcripts, an asynchronous Whisper transcription path for videos without captions, and a saved library.
- Discovery: search_youtube across videos, channels and playlists returning up to 50 results, resolve_channel turning a @handle, channel URL, video URL or raw id into canonical channel info with subscriber and video counts, and search_channel_videos for finding one video inside a known channel.
- Channel and playlist listings — list_channel_videos at up to 30 per page with a continuation token, get_channel_latest_videos as the shortcut with no pagination, and list_playlist_videos with each video's position in the list.
- fetch_video_info for consolidated metadata with numeric types: title, channel, duration, view count, publish date, thumbnail, description and captions availability, without the transcript itself.
- fetch_transcript for the existing official captions with per-segment timestamps and detected language, which errors with NO_CAPTIONS when the video has none.
- transcribe_video, which starts an asynchronous Whisper transcription and returns a task_id with an estimated wait, and get_asr_task, which reports queued, downloading, transcribing, finalizing, done or failed and returns the full timestamped transcript once done.
- A library: save_to_library bookmarks a video, uploads a summary or does both and is idempotent on repeat saves, list_library searches saved titles and authors with a favourites filter and paging, and get_library_item returns the saved transcript and AI summary inline.
An authenticated user for the library, since save_to_library, list_library and get_library_item are scoped to the calling user's own data. Credits for AI transcription: transcribe_video costs 5 credits, debited only on successful completion, while the metadata, caption and library reads are free.
One command plus a key — docker run --rm -i -e SUBDOWNLOAD_API_KEY=YOUR_API_KEY subdownload-mcp, then supply credentials