Skip to main content
Glama

SubDownload MCP Server

SubDownload exposes YouTube as an MCP-native data source. Connect once via OAuth and your AI agent gets tools to summarize videos, fetch full transcripts (including videos without captions, via AI ASR), search channels and playlists, and save everything into a per-user knowledge base for cross-session recall.

The recommended setup is to point your MCP client directly at the hosted endpoint above and authenticate via OAuth — see "Quick connect" below. This repo also ships a thin stdio proxy (Node + Docker) for environments that prefer a local subprocess.

Auth

OAuth 2.1 with Dynamic Client Registration (RFC 7591). No pre-shared client_id or client_secret — your MCP client registers itself on first connect.

Discovery (RFC 9728):

  1. POST to /mcp without a token returns 401 plus a WWW-Authenticate header pointing to /.well-known/oauth-protected-resource

  2. That document points to the authorization server (https://api.subdownload.com)

  3. The MCP client follows the standard authorize → callback → token flow with PKCE

API-key alternative: every account at https://subdownload.com/account exposes a Bearer token for clients that don't support OAuth.

Related MCP server: YouTube Transcript MCP Server

Tools

Tool

What it does

search_youtube

Keyword search across YouTube

fetch_video_info

Video metadata (title, channel, duration, view count)

fetch_transcript

Full transcript with timestamps

transcribe_video

Generate a transcript with AI ASR for videos that have no captions

get_asr_task

Poll an in-progress AI transcription job

resolve_channel

Look up a channel by handle, URL, or ID

list_channel_videos

List videos on a channel

get_channel_latest_videos

Latest videos for a channel

search_channel_videos

Search within a single channel

list_playlist_videos

List the contents of a playlist

save_to_library

Save a video summary or transcript to your personal knowledge base

list_library

Browse your saved knowledge base

get_library_item

Fetch a single saved item

Quick connect

Claude Desktop / Cursor / Windsurf / any OAuth-capable MCP client

{
  "mcpServers": {
    "subdownload": {
      "url": "https://api.subdownload.com/mcp"
    }
  }
}

The first time you use it, the client triggers OAuth and you sign in with Google or LINUX DO. Free credits on signup — no card required.

Bearer-token clients

{
  "mcpServers": {
    "subdownload": {
      "url": "https://api.subdownload.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Grab your API key from your account page.

Local stdio proxy (Docker / npm)

For clients that prefer a subprocess transport, this repo ships a thin Node proxy that forwards tools/call to the hosted endpoint with your API key.

# Docker
docker build -t subdownload-mcp .
docker run --rm -i -e SUBDOWNLOAD_API_KEY=YOUR_API_KEY subdownload-mcp

# Or via Node directly
npm install
SUBDOWNLOAD_API_KEY=YOUR_API_KEY npm start

Client config example:

{
  "mcpServers": {
    "subdownload": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "-e", "SUBDOWNLOAD_API_KEY", "subdownload-mcp"],
      "env": { "SUBDOWNLOAD_API_KEY": "YOUR_API_KEY" }
    }
  }
}

Tool schemas are declared inline so introspection (initialize, tools/list) works without credentials; tools/call requires SUBDOWNLOAD_API_KEY.

Pricing

Free credits on signup. Pro: 5,000 credits per month. See https://subdownload.com/pricing.

Support

License

MIT (applies to this documentation repository; the SubDownload service itself is hosted SaaS — see https://subdownload.com/terms).

Available Tools

13 tools
fetch_transcriptA
Read-only

Fetch the existing official transcript (subtitles/captions) of a YouTube video, with per-segment timestamps and language detected. Errors with NO_CAPTIONS if the video has no captions — fall back to transcribe_video in that case to generate one with AI ASR. This call is free.

Inputs: video_id (required), lang, save.

fetch_video_infoA
Read-only

Fetch consolidated YouTube video metadata with numeric types — title, channel, duration, view count, publish date, thumbnail, description, captions availability. Does NOT include the transcript itself; call fetch_transcript or transcribe_video for that. Cheap, fast, free.

Inputs: video_id (required).

get_asr_taskA
Read-only

Poll the status of an ASR task created by transcribe_video. Returns one of queued, downloading, transcribing, finalizing, done, or failed. When status is done, includes the full transcript with timestamps. Recommended polling interval: 3-5 seconds. Free — does not consume credits.

Inputs: task_id (required).

get_channel_latest_videosA
Read-only

Get the most recent videos from a YouTube channel — convenience wrapper over list_channel_videos with no pagination. Best for 'what did this creator publish recently?' style queries.

Inputs: channel (required).

get_library_itemA
Read-only

Read a saved Library item with its transcript and AI summary inline (when available). Use after list_library to fetch the full content the user saved. Free.

Inputs: id (required), locale.

list_channel_videosA
Read-only

List all videos from a YouTube channel ordered by publish date (newest first), with pagination. Returns up to 30 per page plus a continuation token if more results exist. For just the most recent handful, prefer get_channel_latest_videos for simplicity.

Inputs: channel, continuation.

list_libraryA
Read-only

List videos the user has saved to their Library (transcripts + summaries). Supports substring search on title/author, favorites filter, and pagination. Returns recently saved items first. Scoped to the calling user's data only.

Inputs: favorite, q, limit, offset.

list_playlist_videosA
Read-only

List videos in a YouTube playlist in order, with pagination. Returns video metadata and position within the playlist. Works for any public or unlisted playlist exposed by its URL/ID.

Inputs: playlist, continuation.

resolve_channelA
Read-only

Resolve a YouTube @handle, channel URL, video URL, or raw channel ID into canonical channel info (channel ID, name, handle, subscriber count, video count, avatar). Call this first when you only have a handle or URL but need a channel ID for the other channel-scoped tools.

Inputs: input (required).

save_to_libraryA
Idempotent

Save a video to the authenticated user's Library. Three modes via kind: 'asr' bookmarks the video and flips has_asr (use after a successful transcribe_video → fetch_transcript flow); 'summary' uploads a summary blob; 'both' does both at once. Idempotent: saving the same video twice updates the existing entry.

Inputs: video_id (required), kind (required), title, author, +7 more.

search_channel_videosA
Read-only

Search for specific videos within a single YouTube channel. Restricts results to the given channel. Use after resolve_channel if starting from a handle. Useful for 'find Karpathy's video about backpropagation' style queries.

Inputs: channel (required), q (required), limit.

search_youtubeA
Read-only

Search YouTube globally for videos, channels, or playlists on any topic. Returns up to 50 results with metadata. Use this for topic-based discovery when the user has not specified a channel — for searching within a known channel use search_channel_videos instead.

Inputs: q (required), type, limit.

transcribe_videoA
Idempotent

Start an asynchronous AI ASR (Whisper) transcription of a YouTube video. Returns immediately with a task_id and estimated_wait_seconds; the actual transcription runs in the background. Poll status with get_asr_task. Use this when fetch_transcript returned NO_CAPTIONS or when the video has no captions. Costs 5 credits, debited only on successful completion.

Inputs: video_url (required), lang.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.3/5.0

    Scored across 13 tools

    Disambiguation4/5

    Most tools have clearly distinct purposes, but fetch_transcript vs transcribe_video and list_channel_videos vs get_channel_latest_videos overlap enough that users could initially pick the wrong one. The descriptions provide good disambiguation, so only a slight deduction.

    Naming Consistency5/5

    All tools follow a consistent verb_noun snake_case pattern: list_, get_, fetch_, search_, transcribe_, resolve_, save_. Minor variation between 'fetch' and 'get' is semantically negligible and does not break the pattern.

    Tool Count5/5

    13 tools is well within the ideal range for this domain, covering channel discovery, video search, transcript fetch/generation, ASR status polling, and library management without unnecessary bloat.

    Completeness4/5

    The toolset covers the main workflows of finding videos, fetching or generating transcripts, and saving/reading library items. Obvious gaps are the lack of a library delete/update tool and no way to list available caption tracks before requesting a transcript.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers