YouTube Tools MCP Server
A powerful Model Context Protocol (MCP) server that enables AI assistants to search YouTube and extract video transcripts. Built with TypeScript and designed for seamless integration with Claude Desktop and other MCP-compatible clients.
🎯 What is this?
This MCP server bridges the gap between AI assistants and YouTube content by providing comprehensive YouTube integration capabilities. It allows you to:
- Search YouTube videos using the official YouTube Data API v3
- Extract full transcripts from any YouTube video (when available)
- Store and retrieve video summaries using a local libsql database
- Filter search results by date, duration, quality, and more
- Get timestamped transcript segments for precise referencing
- Support multiple languages for international content
- Handle various YouTube URL formats automatically
Perfect for content discovery, analysis, research, accessibility, and AI-powered video content workflows.
✨ Features
- 🔍 YouTube Video Search: Search YouTube using the official YouTube Data API v3
- 🎬 YouTube Transcript Extraction: Get complete transcripts from YouTube videos using RapidAPI
- 💾 Video Summary Storage: Store and retrieve video summaries using local libsql database
- 🎯 Advanced Search Filters: Filter by date, duration, quality, view count, and more
- 🔗 Flexible Input Formats: Supports video IDs, full URLs, short URLs, and embed URLs
- 🌍 Multi-Language Support: Extract transcripts in different languages when available
- ⚡ Smart Error Handling: Comprehensive error handling with clear, actionable messages
- 🛠️ MCP Protocol Compliant: Built with the official MCP SDK for maximum compatibility
- 🔑 Official API Integration: Uses YouTube Data API v3 and RapidAPI for reliable service
- 💻 CLI Tool Included: Command-line interface for direct transcript extraction
🚀 Quick Start
Prerequisites
- Node.js 18+
- pnpm (recommended) or npm
- Claude Desktop (for usage)
- YouTube Data API v3 Key (for search functionality)
- RapidAPI Account (for transcript extraction)
Installation
-
Clone and install dependencies:
git clone <repository-url> cd youtube-tools-mcp pnpm install -
Set up API Keys:
YouTube Data API v3 (for search):
- Go to Google Cloud Console
- Create a new project or select existing one
- Enable the YouTube Data API v3
- Create credentials (API key)
- Copy your YouTube API key
RapidAPI (for transcripts):
- Go to RapidAPI YouTube Transcripts
- Subscribe to the API (free tier available)
- Copy your RapidAPI key
-
Configure environment:
# Create .env file and add your API keys: YOUTUBE_API_KEY=your_youtube_api_key_here RAPIDAPI_KEY=your_rapidapi_key_here # Optional: Specify custom database path for video summaries DATABASE_PATH=./video_summaries.db -
Build the project:
pnpm run build -
Test your setup:
node temp/test-rapidapi.js -
Configure Claude Desktop:
Add to your Claude Desktop config file (
~/Library/Application Support/Claude/claude_desktop_config.json):{ "mcpServers": { "youtube-tools": { "command": "node", "args": ["/absolute/path/to/youtube-tools-mcp/build/index.js"], "env": { "YOUTUBE_API_KEY": "your_youtube_api_key_here", "RAPIDAPI_KEY": "your_rapidapi_key_here", "DATABASE_PATH": "/absolute/path/to/youtube-tools-mcp/video_summaries.db" } } } }Important:
- Replace
/absolute/path/to/youtube-tools-mcpwith your actual project path - Replace the API keys with your actual keys
- The
DATABASE_PATHis optional - if omitted, it defaults tovideo_summaries.dbin the project root
- Replace
-
Restart Claude Desktop completely.
-
Test it out! Try asking Claude:
"Get the transcript for this YouTube video: https://www.youtube.com/watch?v=2nkiHeoPTqQ"
💻 CLI Usage
You can also use the included command-line tool:
# Basic usage
node cli.js 2nkiHeoPTqQ
# With full URL
node cli.js "https://www.youtube.com/watch?v=2nkiHeoPTqQ"
# Specify language
node cli.js 2nkiHeoPTqQ --language es
# Save to file
node cli.js 2nkiHeoPTqQ --output transcript.txt
# JSON format
node cli.js 2nkiHeoPTqQ --json
# Hide timestamps
node cli.js 2nkiHeoPTqQ --no-timestamps
# Show help
node cli.js --help
📖 Usage Examples
Once configured with Claude Desktop, you can use natural language to interact with YouTube:
Search Examples
Basic search:
"Search YouTube for 'javascript tutorial' videos"
Search with filters:
"Find recent React tutorials from the last month, ordered by view count"
Search for specific content:
"Search for Python programming videos that are medium length and high definition"
Transcript Examples
Get transcript from URL:
"Get the transcript for this YouTube video: https://www.youtube.com/watch?v=2nkiHeoPTqQ"
Use just the video ID:
"Extract transcript from YouTube video ID 2nkiHeoPTqQ"
Specify language:
"Get the Spanish transcript for this video: https://www.youtube.com/watch?v=example"
Works with different URL formats:
- Full URL:
https://www.youtube.com/watch?v=dQw4w9WgXcQ - Short URL:
https://youtu.be/dQw4w9WgXcQ - Embed URL:
https://www.youtube.com/embed/dQw4w9WgXcQ - Video ID:
dQw4w9WgXcQ
Video Summary Examples
Store a video summary:
"Store this summary for video dQw4w9WgXcQ: This is a classic music video featuring Rick Astley's hit song Never Gonna Give You Up."
Retrieve a stored summary:
"Get the stored summary for video ID dQw4w9WgXcQ"
Check if a summary exists:
"Do we have a summary stored for this YouTube video: https://www.youtube.com/watch?v=dQw4w9WgXcQ"
🔧 Available Tools
search_youtube
Search for YouTube videos using the official YouTube Data API v3.
Parameters:
query(required): Search query for YouTube videosmaxResults(optional): Maximum number of results to return (1-50, default: 10)order(optional): Order of results - "relevance", "date", "rating", "viewCount", "title" (default: "relevance")publishedAfter(optional): Return videos published after this date (RFC 3339 format)publishedBefore(optional): Return videos published before this date (RFC 3339 format)videoDuration(optional): Filter by duration - "any", "short", "medium", "long" (default: "any")videoDefinition(optional): Filter by definition - "any", "high", "standard" (default: "any")
Sample Output:
YouTube Search Results for: "javascript tutorial"
📊 Total Results Available: 1000000
📋 Results Returned: 3
🔄 Ordered by: relevance
--- SEARCH RESULTS ---
1. **JavaScript Tutorial for Beginners**
📺 Channel: Programming with Mosh
📅 Published: 1/15/2023
🔗 URL: https://www.youtube.com/watch?v=W6NZfCO5SIk
📝 Video ID: W6NZfCO5SIk
📄 Description: Learn JavaScript fundamentals in this comprehensive tutorial...
2. **Modern JavaScript Course**
📺 Channel: The Net Ninja
📅 Published: 3/22/2023
🔗 URL: https://www.youtube.com/watch?v=iWOYAxlnaww
📝 Video ID: iWOYAxlnaww
📄 Description: Master modern JavaScript with this complete course...
get_youtube_transcript
Extract complete transcripts from YouTube videos using RapidAPI.
Parameters:
videoId(required): YouTube video ID or any YouTube URL formatlanguage(optional): Language code for transcript (e.g., "en", "es", "fr", default: "en")
Sample Output:
YouTube Transcript for Video ID: W6NZfCO5SIk
📊 Total Segments: 245
⏱️ Duration: 1:23:45
--- TRANSCRIPT ---
[0:00] Welcome to this JavaScript tutorial for beginners
[0:05] In this video we're going to learn the fundamentals
[0:12] Let's start with variables and data types
...
storeVideoSummary
Store or update a video summary in the local database.
Parameters:
videoId(required): YouTube video IDsummary(required): Video summary text to store
Sample Output:
Successfully stored summary for video ID: W6NZfCO5SIk
fetchExistingVideoSummary
Fetch an existing video summary from the local database.
Parameters:
videoId(required): YouTube video ID
Sample Output:
Summary for video ID: W6NZfCO5SIk
This is a comprehensive JavaScript tutorial covering fundamentals like variables, functions, and DOM manipulation. Perfect for beginners looking to learn modern JavaScript development.
Note: Returns "No summary found" if no summary exists for the given video ID.
🛠️ Development
Available Scripts
pnpm run build- Compile TypeScript to JavaScriptpnpm run dev- Watch mode for development (auto-rebuild on changes)pnpm start- Run the compiled server directlypnpm run test- Test YouTube transcript functionalitypnpm run test-mcp- Test MCP server functionalitypnpm run test-search- Test YouTube search API functionalitypnpm run test-mcp-search- Test MCP server with search functionality
Project Structure
youtube-tools-mcp/
├── src/
│ ├── index.ts # Main MCP server implementation
│ └── database.ts # Database service for video summaries
├── build/ # Compiled JavaScript output
├── docs/ # Documentation and examples
├── temp/ # Test files and utilities
├── video_summaries.db # Local libsql database (auto-created)
├── package.json # Dependencies and scripts
├── .env.example # Environment variables template
└── README.md # This file
Testing
Test the server functionality:
# Test YouTube transcript extraction
pnpm run test
# Test YouTube search API
pnpm run test-search
# Test MCP server protocol
pnpm run test-mcp
# Test MCP server with search functionality
pnpm run test-mcp-search
# Test database functionality (video summary storage/retrieval)
node temp/test-database-functionality.js
# Manual server test (runs until Ctrl+C)
pnpm start
⚠️ Error Handling
The server provides clear error messages for common scenarios:
| Error | Cause | Solution |
|---|---|---|
| "Transcript is disabled" | Video creator disabled transcripts | Try a different video |
| "No transcript found" | No transcript in requested language | Try "en" or check available languages |
| "Video unavailable" | Private, deleted, or restricted video | Verify the video is public and accessible |
| "Invalid video ID" | Malformed URL or ID | Check the YouTube URL format |
🔧 Troubleshooting
Server not appearing in Claude Desktop?
- Verify the absolute path in your config is correct
- Ensure the project built successfully (
pnpm run build) - Restart Claude Desktop completely
- Check Claude's logs:
~/Library/Logs/Claude/mcp*.log
Tool calls failing?
- Test the server manually:
pnpm start - Verify the video has transcripts available
- Try with a different video
- Check the video is public and not region-restricted
📦 Dependencies
- @modelcontextprotocol/sdk - Official MCP SDK for TypeScript
- @libsql/client - libsql client for local database storage
- axios - HTTP client for API requests
🤝 Contributing
Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
📄 License
MIT License - see LICENSE file for details.
Built with ❤️ using the Model Context Protocol