jandal/yt-caption-mcp-server

YouTube Caption MCP Server

A Model Context Protocol (MCP) server that provides tools for downloading, cleaning, and summarising YouTube video captions. Built with TypeScript and designed for integration with Claude Desktop and other MCP-compatible clients.

Features

• 🎬 Download YouTube Captions: Uses yt-dlp to download English captions from YouTube videos
• 🧹 Clean VTT Files: Removes timestamps, markup, and duplicates to extract clean, readable text
• 💾 Save to Filesystem: Automatically saves cleaned text and summaries to your local filesystem
• 📊 Generate Summaries: Creates intelligent summaries with reading time estimates and key topics
• 🔧 Health Monitoring: Built-in health checks and comprehensive error handling

Prerequisites

• Node.js 18+
• yt-dlp installed and accessible in PATH

  # Install yt-dlp
  pip install yt-dlp
  # or on macOS
  brew install yt-dlp
  

Installation

1. Install dependencies:

   npm install
   

2. Build the project:

   npm run build
   

3. Test the server:

   npm run inspect
   

Configuration for Claude Desktop

Add this server to your Claude Desktop configuration file:

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

{
  "mcpServers": {
    "youtube-captions": {
      "command": "node",
      "args": ["C:\\path\\to\\youtube-caption-mcp\\build\\index.js"],
      "env": {
        "LOG_LEVEL": "info"
      }
    }
  }
}

Available Tools

1. process-youtube-captions

Complete end-to-end caption processing workflow.

Parameters:

• url (required): YouTube video URL
• outputDir (optional): Directory to save files
• filename (optional): Base filename for saved files
• includeRawCaptions (optional): Whether to save raw VTT file

Example:

{
  "url": "https://www.youtube.com/watch?v=example",
  "outputDir": "C:\\Downloads\\captions",
  "filename": "my_video_captions",
  "includeRawCaptions": true
}

2. download-youtube-captions

Download raw VTT caption files only.

Parameters:

• url (required): YouTube video URL
• outputDir (optional): Directory to save VTT file

3. clean-vtt-file

Clean existing VTT files to extract readable text.

Parameters:

• vttFilePath (required): Path to VTT file
• outputPath (optional): Output path for cleaned text

4. health-check

Verify server and dependency status.

Usage Examples

Process a YouTube Video

# In Claude Desktop, use:
@youtube-captions process-youtube-captions url="https://www.youtube.com/watch?v=dQw4w9WgXcQ" outputDir="./captions"

Clean an Existing VTT File

@youtube-captions clean-vtt-file vttFilePath="./my-video.en-orig.vtt" outputPath="./cleaned.txt"

File Output Structure

When processing a YouTube video, the server creates:

output-directory/
├── video-title_2025-01-15T14-30-25.txt      # Cleaned caption text
├── video-title_2025-01-15T14-30-25_summary.txt  # Content summary
└── video-title_2025-01-15T14-30-25_raw.vtt  # Raw VTT (if requested)

Development

Scripts

• npm run build - Compile TypeScript
• npm run dev - Watch mode compilation
• npm start - Run the built server
• npm run inspect - Debug with MCP Inspector
• npm run clean - Remove build files

Project Structure

src/
├── index.ts              # Entry point
├── server.ts             # Main server setup
├── tools/
│   └── youtube-tools.ts  # Tool implementations
└── utils/
    ├── youtube-downloader.ts  # yt-dlp integration
    ├── caption-cleaner.ts     # VTT cleaning logic
    └── file-manager.ts        # File operations & summaries

Error Handling

The server includes comprehensive error handling:

• Invalid URLs: Validates YouTube URL format
• Missing Dependencies: Checks for yt-dlp availability
• File System Errors: Handles permission and path issues
• Network Issues: Graceful handling of download failures

All errors include detailed messages and request IDs for troubleshooting.

Logging

Logs are written to stderr only (MCP protocol requirement):

• INFO: Successful operations and progress
• ERROR: Failures with full stack traces
• WARN: Non-critical issues

Business Integration

This MCP server is designed for business analysts and content teams who need to:

• Extract insights from video content
• Process training materials and webinars
• Analyse competitor or industry content
• Create searchable text archives from video libraries

The automated summarisation and key topic extraction make it particularly valuable for content audit workflows and research processes.

License

MIT License - feel free to use in commercial and personal projects.

Troubleshooting

Common Issues

1. yt-dlp not found:

   • Ensure yt-dlp is installed: pip install yt-dlp
   • Check PATH: which yt-dlp (Unix) or where yt-dlp (Windows)

2. Permission denied:

   • Check write permissions for output directory
   • Run with appropriate user permissions

3. No captions available:

   • Video may not have English captions
   • Check video availability and region restrictions

4. Module import errors:

   • Ensure all dependencies are installed: npm install
   • Rebuild the project: npm run build

Run health-check tool to diagnose server status and dependency issues.