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 videosget_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
-
Node.js (version 18 or higher)
bash node --version # Should be 18.0.0 or higher -
yt-dlp - YouTube video downloader
On Windows:bash
winget install yt-dlp.yt-dlp
On macOS:bash
brew install yt-dlp
On Linux/WSL:bash
pip install yt-dlp
Verify installation:bash
yt-dlp --version
Installation
-
Clone or download this repository
bash git clone <repository-url> cd yt-transcript-mcp -
Install dependencies
bash npm install -
Build the project
bash npm run build
Usage
Testing with MCP Inspector
The easiest way to test the server:```bash
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:**```json
{
"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```bash
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:**```json
{
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "YouTube video URL to extract transcript from"
}
},
"required": ["url"]
}
Example Usage:```json
{
"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:**```json
{
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "YouTube video URL to get information from"
}
},
"required": ["url"]
}
Example Usage:```json
{
"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```bash
npm test
```
Tests cover:
- URL validation for various YouTube URL formats
- Error handling for invalid URLs
How It Works
get_transcript Tool
- URL Validation: The server validates that the provided URL is a valid YouTube URL
- Transcript Extraction: Uses
yt-dlp --write-auto-sub --skip-downloadto download only the transcript - File Processing: Reads the downloaded .vtt transcript file
- Cleanup: Automatically removes the downloaded file after reading
- Response: Returns the transcript content to the MCP client
get_video_info Tool
- URL Validation: The server validates that the provided URL is a valid YouTube URL
- Metadata Extraction: Uses
yt-dlp --write-info-json --skip-downloadto download video metadata - JSON Processing: Reads and parses the downloaded .info.json file
- Data Filtering: Extracts relevant metadata fields (title, description, etc.)
- Cleanup: Automatically removes the downloaded file after reading
- 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
-
"yt-dlp not found"
- Ensure yt-dlp is installed and available in PATH
- Try runningyt-dlp --versionto verify installation -
"No transcript file found"
- The video may not have auto-generated or manual subtitles
- Try with a different video that you know has subtitles -
"Permission denied"
- Ensure the server has write permissions in the current directory
- Check file system permissions -
MCP connection issues
- Verify Node.js version (18+ required)
- Check that the built files exist indist/
- Ensure the path in MCP configuration is correct
License
MIT License - see LICENSE file for details.
