Skip to main content
Glama

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

  1. 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-dlp

    For 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-cffi is yt-dlp's optional networking dependency, not a dependency of the cookie-preservation plugin described below.

  2. ffmpeg - Media file converter

    # Install via Homebrew (macOS)
    brew install ffmpeg
    
    # Or via apt (Linux)
    sudo apt install ffmpeg
  3. Node.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.json

  • Windows: %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

  1. Clone this repository

  2. Install dependencies:

    npm install
  3. Make 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 URL

  • save_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 true to 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 example chrome:Profile 2 or firefox. Defaults to chrome: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.txt

How It Works

  1. Extracts the video ID from the provided YouTube URL

  2. Downloads English subtitles (VTT format) using yt-dlp

  3. Converts VTT to SRT format using ffmpeg

  4. Extracts and deduplicates text content

  5. Cleans up temporary files

  6. 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_ID

  • https://youtu.be/VIDEO_ID

  • https://www.youtube.com/shorts/VIDEO_ID

  • https://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 start

The 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:

  1. Update the package name in package.json to something unique

  2. Update the repository URLs to your GitHub repository

  3. Add your author information

  4. Login to npm:

    npm login
  5. Publish:

    npm publish

Before publishing, make sure to:

  • Test the package locally using npm pack and npm install -g ./yt-subs-mcp-1.0.0.tgz

  • Update 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 tool
get_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

    A4/5.0

    Scored across 1 tool

    Disambiguation5/5

    With only one tool, there is no possibility of confusion between tool purposes. The tool's function is clearly distinct and unambiguous.

    Naming Consistency5/5

    The single tool name follows a clear verb_noun pattern (get_youtube_transcript), which is consistent and predictable.

    Tool Count3/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A powerful text extraction service that converts YouTube video content into clean, timestampless transcripts for content analysis, research, and processing workflows.
      3
      Apache 2.0
    • A
      license
      A
      quality
      C
      maintenance
      Extract YouTube transcripts for AI agents, RAG pipelines, and LLM workflows. Supports any YouTube URL. Returns clean text or timestamped segments. No API keys required.
      1
      4
      MIT