How do I use YouTube Subtitle MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@YouTube Subtitle MCP Server fetch subtitles from https://youtu.be/dQw4w9WgXcQ in SRT format" 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 Subtitle MCP Server

Q: Which integrations are available for this server?

Enables fetching subtitles and transcripts from public YouTube videos with support for multiple output formats (SRT, VTT, TXT, JSON), multi-language subtitle support, and complete timestamp information.

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

License TypeScript MCP

✨ 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

Parameter	Type	Required	Description	Example
`url`	string	✅ Yes	YouTube video URL or video ID	`https://www.youtube.com/watch?v=dQw4w9WgXcQ`
`format`	string	❌ No	Output format (default: JSON)	`SRT`, `VTT`, `TXT`, `JSON`
`lang`	string	❌ No	Language code (default: auto)	`zh-Hans`, `en`, `ja`

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 up -d

🚀 Deployment

PM2 (Process Manager)

# Install PM2 npm install -g pm2 # Start service pm2 start build/httpServer.js --name youtube-subtitle-mcp # View status pm2 status # View logs pm2 logs youtube-subtitle-mcp # Restart pm2 restart youtube-subtitle-mcp # Stop pm2 stop youtube-subtitle-mcp

🔍 API Reference

Health Check (HTTP Mode)

Endpoint: GET /health

Response:

{ "status": "healthy", "transport": "streamable-http", "activeSessions": 0, "name": "youtube-subtitle-mcp", "version": "1.0.0", "timestamp": "2024-01-01T12:00:00.000Z" }

MCP Endpoint (HTTP Mode)

Endpoint: POST /mcp

Headers:

Content-Type: application/json
Mcp-Session-Id: <session-id> (after initialization)

Request Body: JSON-RPC 2.0 format

⚠️ Notes

Public videos only: Cannot fetch subtitles from private or restricted videos
Subtitles required: Video must have available subtitles (auto-generated or uploaded)
Language codes: If specified language doesn't exist, an error will be returned
Network required: Requires stable network connection to access YouTube
Terms of Service: Please comply with YouTube's Terms of Service, use for research/analysis purposes only

❓ FAQ

Q: Server started but client can't connect?

A: Check the following:

Verify server is running: visit http://localhost:3000/health
Check URL in configuration file: http://localhost:3000/mcp
Ensure firewall isn't blocking port 3000
Restart Cursor/Claude Desktop

Q: Why can't I fetch subtitles?

A: Possible reasons:

Video has no subtitles
Video is private or region-restricted
Specified language code doesn't exist
Network connection issue
Server network can't access YouTube

Q: Do you support auto-generated subtitles?

A: Yes, supports YouTube auto-generated subtitles.

Q: Can I batch process multiple videos?

A: Current version processes one video at a time. For batch processing, loop the tool call on the client side.

Q: What's the timestamp unit?

A: Timestamps in JSON format are in milliseconds (ms).

Q: Can I deploy on a remote server?

A: Yes! Just:

Install Node.js on remote server
Clone project and run npm install
Start server with npm run start:http
Use remote URL in client configuration: http://your-server:3000/mcp
Recommend using HTTPS and reverse proxy (e.g., Nginx) for security

Q: How to change port?

A: Two methods:

Environment variable: PORT=8080 npm run start:http
Create .env file: add PORT=8080

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

👤 Author

Xingyu Chen

LinkedIn: https://www.linkedin.com/in/xingyu-chen-b5b3b0313/
Email: guangxiangdebizi@gmail.com
GitHub: https://github.com/guangxiangdebizi/
NPM: https://www.npmjs.com/~xingyuchen

🙏 Acknowledgments

Model Context Protocol - MCP SDK
youtubei.js - Powerful YouTube API wrapper for reliable subtitle extraction

📮 Support

If you have any questions or suggestions, please create an Issue.

Made with ❤️ by Xingyu Chen