YouTube Subtitles MCP Server

An MCP (Model Context Protocol) server that fetches YouTube video subtitles/captions using the youtube-captions-scraper package.

Features

• Fetch subtitles from any YouTube video
• Support for multiple language codes
• Accepts both video IDs and full YouTube URLs
• Returns both timestamped and plain text versions of subtitles

Installation

From npm (Recommended)

npm install -g youtube-subtitles-mcp

or use with npx (no installation required):

npx youtube-subtitles-mcp

From source

git clone <repository-url>
cd yt-mcp
pnpm install

Usage

This MCP server exposes a single tool:

get-video-subtitles

Fetches subtitles for a YouTube video.

Parameters:

• videoId (required): YouTube video ID (e.g., 'dQw4w9WgXcQ') or full YouTube URL
• lang (optional): Language code for subtitles (e.g., 'en' for English). Defaults to 'en'

Supported URL formats:

• https://www.youtube.com/watch?v=VIDEO_ID
• https://youtu.be/VIDEO_ID
• https://www.youtube.com/embed/VIDEO_ID
• https://www.youtube.com/v/VIDEO_ID
• Or just the video ID: VIDEO_ID

Example response: Returns subtitles in two formats:

1. Timestamped subtitles with start times and durations
2. Plain text version without timestamps

Running the Server

The server uses stdio transport and can be integrated with any MCP-compatible client.

node index.js

Configuration

Add this server to your MCP client configuration.

Using the published npm package (Recommended)

For Claude Desktop, Windsurf, or Cursor, add to your MCP settings:

{
  "mcpServers": {
    "youtube-subtitles": {
      "command": "npx",
      "args": ["-y", "youtube-subtitles-mcp"]
    }
  }
}

Using local installation

{
  "mcpServers": {
    "youtube-subtitles": {
      "command": "node",
      "args": ["/absolute/path/to/yt-mcp/index.js"]
    }
  }
}

Error Handling

The server handles various error cases:

• Invalid video IDs
• Missing subtitles
• Unsupported languages
• Network errors

All errors are returned with descriptive messages.

Dependencies

• @modelcontextprotocol/sdk: MCP SDK for server implementation
• youtube-captions-scraper: Package to fetch YouTube captions
• zod: Schema validation

License

ISC