YouTube Subtitle MCP Server

A Model Context Protocol (MCP) server for fetching YouTube video subtitles/transcripts with support for multiple output formats (SRT, VTT, TXT, JSON).

Features

• Fetch subtitles from any public YouTube video
• Multiple output formats: SRT, VTT, TXT, JSON
• Multi-language subtitle support
• Two deployment modes: stdio (local) and HTTP (server)
• Zero-configuration setup with npx
• Complete timestamp information
• Production-ready with TypeScript
• Built with youtubei.js for reliable and stable subtitle extraction

Quick Start

Method 1: stdio Mode (Recommended for Local Use)

Zero configuration required! Simply use npx:

npx -y youtube-subtitle-mcp

Or install globally:

npm install -g youtube-subtitle-mcp
youtube-subtitle-mcp

Method 2: HTTP Mode (For Server Deployment)

# Clone repository
git clone https://github.com/guangxiangdebizi/youtube-subtitle-mcp.git
cd youtube-subtitle-mcp

# Install dependencies
npm install

# Build
npm run build

# Start HTTP server
npm run start:http

Server will start at http://localhost:3000

Installation

For Development

# Clone repository
git clone https://github.com/guangxiangdebizi/youtube-subtitle-mcp.git
cd youtube-subtitle-mcp

# Install dependencies
npm install

# Build
npm run build

For Production

npm install -g youtube-subtitle-mcp

Configuration

stdio Mode Configuration (Recommended)

Add to your MCP client configuration file:

Claude Desktop / Cursor Configuration:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

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

For local development:

{
  "mcpServers": {
    "youtube-subtitle": {
      "command": "node",
      "args": ["C:/path/to/youtube-subtitle-mcp/build/index.js"]
    }
  }
}

HTTP Mode Configuration

{
  "mcpServers": {
    "youtube-subtitle": {
      "type": "streamableHttp",
      "url": "http://localhost:3000/mcp",
      "timeout": 600
    }
  }
}

Tool: fetch_youtube_subtitles

Parameters

Supported URL Formats

• Standard: https://www.youtube.com/watch?v=VIDEO_ID
• Short: https://youtu.be/VIDEO_ID
• Embed: https://www.youtube.com/embed/VIDEO_ID
• Direct ID: VIDEO_ID

Language Codes

• zh-Hans - Simplified Chinese
• zh-Hant - Traditional Chinese
• en - English
• ja - Japanese
• ko - Korean
• es - Spanish
• fr - French
• de - German

Usage Examples

Example 1: Fetch JSON Format Subtitles (Default)

Please fetch subtitles from this video:
https://www.youtube.com/watch?v=dQw4w9WgXcQ

Example 2: Fetch SRT Format Subtitles

Please fetch subtitles in SRT format from:
https://www.youtube.com/watch?v=dQw4w9WgXcQ

Example 3: Fetch Specific Language Subtitles

Please fetch Simplified Chinese subtitles in VTT format from:
https://www.youtube.com/watch?v=dQw4w9WgXcQ
Language code: zh-Hans

Example 4: Fetch Plain Text Content

Please fetch plain text subtitles from:
https://youtu.be/dQw4w9WgXcQ
Format: TXT

Output Format Examples

JSON Format

[
  {
    "text": "Hello world",
    "start": 0,
    "end": 2000,
    "duration": 2000
  },
  {
    "text": "Welcome to YouTube",
    "start": 2000,
    "end": 5000,
    "duration": 3000
  }
]

SRT Format

1
00:00:00,000 --> 00:00:02,000
Hello world

2
00:00:02,000 --> 00:00:05,000
Welcome to YouTube

VTT Format

WEBVTT

00:00:00.000 --> 00:00:02.000
Hello world

00:00:02.000 --> 00:00:05.000
Welcome to YouTube

TXT Format

Hello world
Welcome to YouTube
This is a subtitle example

Project Structure

youtube-subtitle-mcp/
 src/
    index.ts              # stdio mode entry (recommended for local use)
    httpServer.ts         # HTTP mode entry (for server deployment)
    tools/
        fetchYoutubeSubtitles.ts  # Main tool implementation
        formatters.ts     # Format converters (SRT/VTT/TXT/JSON)
        utils.ts          # Utility functions
 build/                    # Compiled JavaScript (generated)
 package.json
 tsconfig.json
 README.md

Development

Build

npm run build

Watch Mode

npm run watch

Start stdio Mode

npm run start:stdio

Start HTTP Mode

npm run start:http

Custom Port (HTTP Mode)

PORT=8080 npm run start:http

Docker Deployment

Using Docker

FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
RUN npm run build
EXPOSE 3000
CMD ["npm", "run", "start:http"]

# Build image
docker build -t youtube-subtitle-mcp .

# Run container
docker run -d -p 3000:3000 --name youtube-mcp youtube-subtitle-mcp

Using Docker Compose

version: '3.8'
services:
  youtube-subtitle-mcp:
    build: .
    ports:
      - "3000:3000"
    environment:
      - PORT=3000
    restart: unless-stopped

docker-compose …