yt-subs
This MCP server lets you extract clean English YouTube transcripts from video URLs and optionally save them to disk.
Extract auto-generated or manual English subtitles from YouTube videos.
Return clean, deduplicated transcript text for reading, summarizing, quoting, or searching video content.
Save transcripts as
VIDEO_ID.txttoYT_SUBS_DOWNLOAD_DIRor the default~/Downloads/yts/.Choose whether to save with
save_to_file(default: true) or just return the transcript.Accept common YouTube URL formats such as watch, youtu.be, shorts, and embed URLs.
Optionally read browser cookies for videos requiring a signed-in session via environment configuration.
Extracts clean text transcripts from YouTube videos using subtitles (auto-generated or manual) via the YouTube platform.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@yt-subs transcript of https://youtu.be/dQw4w9WgXcQ"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
YouTube Subtitles MCP Server
An MCP (Model Context Protocol) server that extracts clean text transcripts from YouTube videos using their subtitles.
Features
Extract English subtitles (auto-generated or manual) from YouTube videos
Convert subtitle files to clean, deduplicated plain text
Save transcripts to local files or return them directly
Works with any MCP-compatible client (Claude Desktop, etc.)
Related MCP server: Youtube2Text
Prerequisites
Before using this MCP server, you must have the following tools installed:
Required Dependencies
yt-dlp - YouTube video downloader (use a current version with plugin support)
# Install via Homebrew (macOS) brew install yt-dlp # Or via pip pip install yt-dlpFor browser impersonation support on installations that do not bundle it:
uv tool install 'yt-dlp[default,curl-cffi]' # Or, in your existing Python environment: pip install 'yt-dlp[default,curl-cffi]'curl-cffiis yt-dlp's optional networking dependency, not a dependency of the cookie-preservation plugin described below.ffmpeg - Media file converter
# Install via Homebrew (macOS) brew install ffmpeg # Or via apt (Linux) sudo apt install ffmpegNode.js - Version 18 or higher
# Check your version node --version # Install via Homebrew (macOS) brew install node
Installation
Quick Start (Using npx)
No installation required! Just add to your MCP client configuration:
{
"mcpServers": {
"yt-subs": {
"command": "npx",
"args": ["-y", "yt-subs-mcp"]
}
}
}Note: You still need to have yt-dlp and ffmpeg installed on your system (see Prerequisites above).
Claude Desktop Configuration
Edit your Claude Desktop config file:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.json
Add the server to the mcpServers section:
Option 1: Using npx (recommended)
{
"mcpServers": {
"yt-subs": {
"command": "npx",
"args": ["-y", "yt-subs-mcp"],
"env": {
"YT_SUBS_DOWNLOAD_DIR": "/path/to/your/transcripts"
}
}
}
}Option 2: Using local installation
{
"mcpServers": {
"yt-subs": {
"command": "node",
"args": ["/absolute/path/to/yt-subs/index.js"]
}
}
}For Local Development
Clone this repository
Install dependencies:
npm installMake the script executable:
chmod +x index.js
Usage
Once configured in your MCP client, you can use the get_youtube_transcript tool:
Tool: get_youtube_transcript
Extracts the subtitle/transcript text from a YouTube video URL.
Parameters:
url(required): The YouTube video URLsave_to_file(optional): Whether to save the transcript to a file (default: true)
Examples:
// Get transcript and save to file
{
"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
"save_to_file": true
}
// Get transcript without saving
{
"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
"save_to_file": false
}Response:
{
"success": true,
"video_id": "dQw4w9WgXcQ",
"transcript": "Never gonna give you up\nNever gonna let you down...",
"saved_to": "/Users/yourname/Downloads/yts/dQw4w9WgXcQ.txt",
"message": "Transcript extracted and saved to /Users/yourname/Downloads/yts/dQw4w9WgXcQ.txt"
}Configuration
Environment Variables
YT_SUBS_DOWNLOAD_DIR: Custom directory for saving transcript files
If not set, defaults to
~/Downloads/yts/Must be an absolute path
Directory will be created if it doesn't exist
YT_SUBS_USE_BROWSER_COOKIES: Set to
trueto let yt-dlp read Chrome cookies for videos requiring a signed-in session. Disabled by default.YT_SUBS_COOKIES_BROWSER: Browser and profile that yt-dlp reads cookies from, in yt-dlp's
BROWSER[:PROFILE]form, for examplechrome:Profile 2orfirefox. Defaults tochrome:Default, Chrome's first profile.YT_SUBS_DOWNLOAD_TIMEOUT_MS: Download deadline in milliseconds; defaults to
300000(five minutes).YT_SUBS_CONVERSION_TIMEOUT_MS: Conversion deadline in milliseconds; defaults to
60000(one minute).YT_SUBS_DEPENDENCY_TIMEOUT_MS: Deadline for each dependency check; defaults to
10000(10 seconds).
Timeout overrides must be positive integers. Requests are limited to two at a time per server process. URLs are limited to 2 KB, and VTT and SRT files are limited to 10 MB each before processing. Playlist downloads are disabled. JavaScript components may still be downloaded automatically from GitHub by yt-dlp (ejs:github).
The MCP server ignores local yt-dlp configuration so that cookie access and output behavior are controlled by the server's settings. Running yt-dlp separately still uses your normal configuration.
When browser cookies are enabled, the server automatically loads its bundled yt-dlp plugin. The plugin snapshots the browser cookies before YouTube extraction and restores them afterward, so subtitle requests use the original browser session. This addresses a case where cookies changed by intermediate YouTube responses cause subtitle HTTP 429 errors even though the same URL works in the browser. It does not bypass genuine rate limits or guarantee every 429 is fixed. Cookies stay in memory; the plugin does not export them or modify the browser's cookie database.
The plugin uses only Python's standard library and yt-dlp's own runtime. No
separate Python executable, wrapper installation, or custom PATH entry is
needed. If migrating from the local cookie-preservation wrapper, remove its
directory from the client's PATH, keep the two browser-cookie environment
variables, and reconnect the server after installing the updated package.
For development, npm test runs the offline plugin regression tests with
python3 (or the executable specified by PYTHON). Those tests require no
third-party Python packages.
Each request uses a private temporary directory, removed on success or failure. Saved transcripts are replaced atomically; save_to_file: false leaves existing transcripts untouched.
Example:
export YT_SUBS_DOWNLOAD_DIR="/path/to/your/transcripts"Setting Environment Variables in Claude Desktop
To use a custom download directory, add the env property to your server configuration:
{
"mcpServers": {
"yt-subs": {
"command": "node",
"args": ["/absolute/path/to/yt-subs/index.js"],
"env": {
"YT_SUBS_DOWNLOAD_DIR": "/path/to/your/transcripts"
}
}
}
}Output Location
By default, transcript files are saved to:
~/Downloads/yts/Or to the directory specified by YT_SUBS_DOWNLOAD_DIR environment variable.
Each transcript is saved with the video ID as the filename:
VIDEO_ID.txtHow It Works
Extracts the video ID from the provided YouTube URL
Downloads English subtitles (VTT format) using yt-dlp
Converts VTT to SRT format using ffmpeg
Extracts and deduplicates text content
Cleans up temporary files
Returns the clean transcript text
Troubleshooting
"Missing required dependencies" error
Make sure yt-dlp and ffmpeg are installed and available in your PATH:
which yt-dlp
which ffmpeg"Failed to download subtitle" error
The video may not have English subtitles available. Try a different video or check if subtitles exist on YouTube.
"Invalid YouTube URL or video ID" error
Ensure you're providing a valid YouTube URL format:
https://www.youtube.com/watch?v=VIDEO_IDhttps://youtu.be/VIDEO_IDhttps://www.youtube.com/shorts/VIDEO_IDhttps://www.youtube.com/embed/VIDEO_ID
Video IDs must contain exactly 11 letters, digits, underscores, or hyphens. Only supported YouTube hosts and HTTP/HTTPS URLs are accepted; downloads use a canonical HTTPS watch URL. URLs with credentials or nonstandard ports are rejected.
Development
Running Locally
npm startThe server will run on stdio and wait for MCP protocol messages.
Testing
Run npm test for integration tests through the real stdio MCP server. The tests use controlled yt-dlp and ffmpeg replacements; they do not download live videos or read browser cookies. You can also test live downloads with an MCP client.
Publishing to npm
If you want to publish your own version to npm:
Update the package name in
package.jsonto something uniqueUpdate the repository URLs to your GitHub repository
Add your author information
Login to npm:
npm loginPublish:
npm publish
Before publishing, make sure to:
Test the package locally using
npm packandnpm install -g ./yt-subs-mcp-1.0.0.tgzUpdate the version number following semver
Ensure README is up to date
Add appropriate tags and keywords
License
MIT
Credits
Based on the yt-subs bash script for extracting YouTube subtitles.
Available Tools
1 toolget_youtube_transcriptA
Extract the subtitle/transcript text from a YouTube video URL. Always use this tool when:
User provides a YouTube URL and wants to read/analyze the video content
User asks what a YouTube video is about or wants a summary
User needs to extract quotes or information from a YouTube video
User wants to search through video content without watching
User needs the transcript saved to a file for reference
Returns the clean text content of the video's English subtitles (auto-generated or manual).
Inputs: url (required), save_to_file.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 1 tool
With only one tool, there is no possibility of confusion between tool purposes. The tool's function is clearly distinct and unambiguous.
The single tool name follows a clear verb_noun pattern (get_youtube_transcript), which is consistent and predictable.
The server has only one tool, which is on the thin side for a general-purpose media analysis server. However, for a focused transcript-extraction niche, it is borderline acceptable.
The tool fully covers the core operation of fetching YouTube transcripts. Some minor gaps exist, such as lack of language selection or support for non-English subtitles, but these are workarounds rather than critical dead ends.
Maintenance
Related MCP Connectors
Transcripts of YouTube videos, playlists and channels with timestamps; SRT or WebVTT too.
Clean YouTube transcripts for agents: single videos, channels, playlists, plus AI caption cleanup.
Transcripts, translations, summaries, subtitles, and search for public YouTube videos.
YouTube video transcripts with timestamps, in bulk for channels, playlists and searches.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables extraction of transcript text from YouTube videos by providing the video URL, supporting standard, shortened, and embed URL formats.18 npm2-
- AlicenseNot gradedqualityDmaintenanceA powerful text extraction service that converts YouTube video content into clean, timestampless transcripts for content analysis, research, and processing workflows.3Apache 2.0
- AlicenseAqualityDmaintenanceRetrieves transcripts from YouTube videos with support for multiple languages, timestamp control, and language detection. Enables video content analysis, summarization, and quote extraction without manually downloading or watching videos.42114 npm16MIT
- AlicenseAqualityCmaintenanceExtract YouTube transcripts for AI agents, RAG pipelines, and LLM workflows. Supports any YouTube URL. Returns clean text or timestamped segments. No API keys required.14MIT