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

1. Clone and install dependencies:

   git clone <repository-url> cd youtube-tools-mcp pnpm install

2. 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

3. 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

4. Build the project:

   pnpm run build

5. Test your setup:

   node temp/test-rapidapi.js

6. 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-mcp with your actual project path

   • Replace the API keys with your actual keys

   • The DATABASE_PATH is optional - if omitted, it defaults to video_summaries.db in the project root

7. Restart Claude Desktop completely.

8. 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:

📖 Usage Examples

Once configured with Claude Desktop, you can use natural language to interact with YouTube:

Search Examples

Basic search:

Search with filters:

Search for specific content:

Transcript Examples

Get transcript from URL:

Use just the video ID:

Specify language:

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:

Retrieve a stored summary:

Check if a summary exists:

🔧 Available Tools

search_youtube

Search for YouTube videos using the official YouTube Data API v3.

Parameters:

• query (required): Search query for YouTube videos

• maxResults (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:

get_youtube_transcript

Extract complete transcripts from YouTube videos using RapidAPI.

Parameters:

• videoId (required): YouTube video ID or any YouTube URL format

• language (optional): Language code for transcript (e.g., "en", "es", "fr", default: "en")

Sample Output:

storeVideoSummary

Store or update a video summary in the local database.

Parameters:

• videoId (required): YouTube video ID

• summary (required): Video summary text to store

Sample Output:

fetchExistingVideoSummary

Fetch an existing video summary from the local database.

Parameters:

• videoId (required): YouTube video ID

Sample Output:

Note: Returns "No summary found" if no summary exists for the given video ID.

🛠️ Development

Available Scripts

• pnpm run build - Compile TypeScript to JavaScript

• pnpm run dev - Watch mode for development (auto-rebuild on changes)

• pnpm start - Run the compiled server directly

• pnpm run test - Test YouTube transcript functionality

• pnpm run test-mcp - Test MCP server functionality

• pnpm run test-search - Test YouTube search API functionality

• pnpm run test-mcp-search - Test MCP server with search functionality

Project Structure

Testing

Test the server functionality:

⚠️ Error Handling

The server provides clear error messages for common scenarios:

🔧 Troubleshooting

Server not appearing in Claude Desktop?

1. Verify the absolute path in your config is correct

2. Ensure the project built successfully (pnpm run build)

3. Restart Claude Desktop completely

4. Check Claude's logs: ~/Library/Logs/Claude/mcp*.log

Tool calls failing?

1. Test the server manually: pnpm start

2. Verify the video has transcripts available

3. Try with a different video

4. 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