dprothero/yt-transcript-mcp

YouTube Transcript MCP Server

A Model Context Protocol (MCP) server that extracts transcripts from YouTube videos using yt-dlp.

Features

• Two Tools:
  • get_transcript - Extracts transcripts from YouTube videos
  • get_video_info - Gets video metadata including title, description, uploader, and more
• URL Validation: Validates YouTube URLs before processing
• Automatic Cleanup: Removes downloaded files after reading
• Error Handling: Proper error handling for command failures and missing files
• TypeScript: Fully typed codebase with comprehensive testing

Prerequisites

Required Software

1. Node.js (version 18 or higher)

   node --version  # Should be 18.0.0 or higher
   

2. yt-dlp - YouTube video downloader

   On Windows:

   winget install yt-dlp.yt-dlp
   

   On macOS:

   brew install yt-dlp
   

   On Linux/WSL:

   pip install yt-dlp
   

   Verify installation:

   yt-dlp --version
   

Installation

1. Clone or download this repository

   git clone <repository-url>
   cd yt-transcript-mcp
   

2. Install dependencies

   npm install
   

3. Build the project

   npm run build
   

Usage

Testing with MCP Inspector

The easiest way to test the server:

npx @modelcontextprotocol/inspector npm run dev

This will open a web interface where you can:

• View available tools
• Test the get_transcript tool with YouTube URLs
• See real-time responses

Integration with Claude Desktop

Add to your Claude Desktop MCP configuration file:

Location:

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

Configuration:

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

Replace /path/to/yt-transcript-mcp/ with the actual path to this project.

Direct Command Line Usage

node dist/index.js

The server communicates via JSON-RPC over stdio.

API Reference

get_transcript Tool

Description: Extract transcript from a YouTube video URL using yt-dlp

Input Schema:

{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "description": "YouTube video URL to extract transcript from"
    }
  },
  "required": ["url"]
}

Example Usage:

{
  "name": "get_transcript",
  "arguments": {
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
  }
}

Response: Returns the transcript content in WebVTT format.

get_video_info Tool

Description: Get video metadata including title, description, uploader, and other details from a YouTube video URL

Input Schema:

{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "description": "YouTube video URL to get information from"
    }
  },
  "required": ["url"]
}

Example Usage:

{
  "name": "get_video_info",
  "arguments": {
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
  }
}

Response: Returns a JSON object with video metadata including:

• title - Video title
• description - Video description
• uploader - Channel/uploader name
• upload_date - Upload date (YYYYMMDD format)
• duration - Video duration in seconds
• view_count - Number of views
• like_count - Number of likes
• channel - Channel name
• tags - Array of video tags
• thumbnail - Thumbnail URL
• webpage_url - Original video URL

Supported URL Formats (both tools)

• https://www.youtube.com/watch?v=VIDEO_ID
• https://youtu.be/VIDEO_ID
• http://youtube.com/watch?v=VIDEO_ID
• youtube.com/watch?v=VIDEO_ID
• youtu.be/VIDEO_ID

Development

Scripts

• npm run dev - Run development server with hot reload
• npm run build - Build TypeScript to JavaScript
• npm test - Run unit tests
• npm run test:watch - Run tests in watch mode
• npm run typecheck - Run TypeScript type checking
• npm run lint - Run ESLint (if configured)

Project Structure

yt-transcript-mcp/
├── src/
│   ├── index.ts          # Main MCP server implementation
│   ├── test-utils.ts     # Utility functions for testing
│   └── index.test.ts     # Unit tests
├── dist/                 # Built JavaScript files
├── package.json
├── tsconfig.json
├── vitest.config.ts
└── README.md

Running Tests

npm test

Tests cover:

• URL validation for various YouTube URL formats
• Error handling for invalid URLs

How It Works

get_transcript Tool

1. URL Validation: The server validates that the provided URL is a valid YouTube URL
2. Transcript Extraction: Uses yt-dlp --write-auto-sub --skip-download <url> to download only the transcript
3. File Processing: Reads the downloaded .vtt transcript file
4. Cleanup: Automatically removes the downloaded file after reading
5. Response: Returns the transcript content to the MCP client

get_video_info Tool

1. URL Validation: The server validates that the provided URL is a valid YouTube URL
2. Metadata Extraction: Uses yt-dlp --write-info-json --skip-download <url> to download video metadata
3. JSON Processing: Reads and parses the downloaded .info.json file
4. Data Filtering: Extracts relevant metadata fields (title, description, etc.)
5. Cleanup: Automatically removes the downloaded file after reading
6. Response: Returns the formatted metadata as JSON to the MCP client

Error Handling

The server handles various error conditions:

• Invalid URLs: Returns error for non-YouTube URLs
• Command Failures: Handles yt-dlp execution errors
• Missing Transcripts: Reports when no transcript file is found
• File System Errors: Handles file read/write issues

Troubleshooting

Common Issues

1. "yt-dlp not found"

   • Ensure yt-dlp is installed and available in PATH
   • Try running yt-dlp --version to verify installation

2. "No transcript file found"

   • The video may not have auto-generated or manual subtitles
   • Try with a different video that you know has subtitles

3. "Permission denied"

   • Ensure the server has write permissions in the current directory
   • Check file system permissions

4. MCP connection issues

   • Verify Node.js version (18+ required)
   • Check that the built files exist in dist/
   • Ensure the path in MCP configuration is correct

License

MIT License - see LICENSE file for details.