Youtube MCP Server

🚀 YouTube MCP Server

A comprehensive Model Context Protocol (MCP) server that offers real - time access to YouTube data via the YouTube Data API v3. It empowers AI assistants to search, analyze, and retrieve detailed information about YouTube videos, channels, playlists, etc.

🚀 Quick Start

To quickly start using the YouTube MCP Server, follow these steps:

1. Clone the repository:

git clone https://github.com/dannySubsense/youtube-mcp-server.git
cd youtube-mcp-server

2. Install dependencies:

pip install -r requirements.txt

3. Obtain a YouTube API Key from the Google Cloud Console.
4. Configure the API Key in a credentials.yml file or set it as an environment variable.
5. Test the server:

python test_server.py

✨ Features

14 Complete Functions

1. get_video_details: Retrieve comprehensive video information, including title, description, statistics, and metadata.
2. get_playlist_details: Fetch playlist information and metadata.
3. get_playlist_items: List videos within a playlist with detailed information.
4. get_channel_details: Obtain channel information, such as subscriber count, video count, and description.
5. get_video_categories: List available video categories for specific regions.
6. get_channel_videos: Get recent videos from a YouTube channel.
7. search_videos: Search YouTube for videos with customizable parameters.
8. get_trending_videos: Retrieve trending videos for specific regions.
9. get_video_comments: Get comments from videos with sorting options.
10. analyze_video_engagement: Analyze engagement metrics and provide insights.
11. get_channel_playlists: List playlists from a YouTube channel.
12. get_video_caption_info: Get available caption/transcript information.
13. evaluate_video_for_knowledge_base: Conduct intelligent content evaluation with freshness scoring for knowledge base curation.
14. get_video_transcript: Extract actual transcript content from YouTube videos.

Key Capabilities

• ✅ Real - time data from YouTube Data API v3
• ✅ Comprehensive error handling and API quota management
• ✅ Multiple URL format support (youtube.com, youtu.be, @usernames, channel IDs)
• ✅ Intelligent content evaluation with technology freshness scoring
• ✅ Flexible search and filtering options
• ✅ Engagement analysis with industry benchmarks
• ✅ Regional content support for trending and categories
• ✅ MCP protocol compliance for seamless AI integration

📦 Installation

Requirements

• Python 3.8+
• YouTube Data API v3 key
• MCP - compatible client (Claude Desktop, Cursor, etc.)
• youtube - transcript - api (for transcript extraction functionality)

Installation Steps

1. Clone the Repository

git clone https://github.com/dannySubsense/youtube-mcp-server.git
cd youtube-mcp-server

2. Install Dependencies

pip install -r requirements.txt

3. Get YouTube API Key
   1. Go to the Google Cloud Console.
   2. Create a new project or select an existing one.
   3. Enable the YouTube Data API v3.
   4. Create credentials (API Key).
   5. (Optional) Restrict the API key to YouTube Data API v3 for security.
4. Configure API Key Create a credentials.yml file in the project root:

youtube_api_key: "YOUR_YOUTUBE_API_KEY_HERE"

Important: Never commit your credentials.yml file to version control! You can also use environment variables:

export YOUTUBE_API_KEY="your_api_key_here"

5. Test the Server

python test_server.py

💻 Usage Examples

Basic Usage

# Get detailed video information
result = await get_video_details("https://www.youtube.com/watch?v=dQw4w9WgXcQ")

# Also works with video IDs
result = await get_video_details("dQw4w9WgXcQ")

Advanced Usage

# Search for recent Python tutorials
tutorials = await search_videos(
    query="Python tutorial",
    max_results=10,
    order="date"
)

# Get trending videos in the US
trending = await get_trending_videos(region_code="US", max_results=5)

📚 Documentation

Integration Guides

Claude Desktop Integration

1. Install the server following the setup steps above.
2. Add to Claude Desktop configuration:
   • Edit your Claude Desktop config file:
     • Windows: %APPDATA%\Claude\claude_desktop_config.json
     • Mac: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "youtube": {
      "command": "python",
      "args": ["/path/to/youtube-mcp-server/youtube_mcp_server.py"],
      "env": {
        "YOUTUBE_API_KEY": "your_youtube_api_key_here"
      }
    }
  }
}

3. Restart Claude Desktop.
4. Verify integration by asking Claude: "Can you search for Python tutorials on YouTube?"

Cursor Integration

1. Install the server following the setup steps above.
2. Configure in Cursor settings:
   • Open Cursor Settings.
   • Navigate to MCP Servers.
   • Add a new server with the python command and arguments.
3. Set the environment variable for your API key.
4. Test with Cursor by asking it to search YouTube content.

Custom Project Integration

from youtube_mcp_server import (
    get_video_details,
    search_videos,
    evaluate_video_for_knowledge_base
)

# Example usage
async def example():
    # Search for videos
    results = await search_videos("machine learning", max_results=5)
    print(results)

    # Evaluate video for knowledge base
    evaluation = await evaluate_video_for_knowledge_base("dQw4w9WgXcQ")
    print(evaluation)

Function Reference

Special Feature: Intelligent Content Evaluation

The evaluate_video_for_knowledge_base function includes advanced content evaluation:

Technology Freshness Scoring

• High - volatility topics (React, AWS, AI/ML): Strong preference for recent content.
• Medium - volatility topics (Python, general programming): Moderate freshness bonus.
• Stable topics (algorithms, math): Minimal age penalty.

Quality Indicators

• View count and engagement metrics.
• Manual vs auto - generated captions.
• Content type detection (tutorial, review, etc.).
• Duration appropriateness.
• Technology currency indicators (2024, 2025, "latest", version numbers).

Smart Recommendations

• 🟢 HIGHLY RECOMMENDED - Strong quality + recent tech content.
• 🟡 MODERATELY RECOMMENDED - Some positive indicators.
• 🔴 LIMITED RECOMMENDATION - Few quality indicators.

API Quota Usage

Daily limit: 10,000 units (default). Monitor usage to avoid quota exhaustion.

Error Handling

The server includes comprehensive error handling for:

• Invalid API keys.
• Quota exceeded errors.
• Network connectivity issues.
• Invalid video/channel IDs.
• Regional restrictions.
• Disabled comments/captions.

Testing

Run the comprehensive test suite:

python test_server.py

This tests all 14 functions with real YouTube content and provides detailed output.

Security Notes

• Never commit your credentials.yml file.
• Restrict your API key to YouTube Data API v3 only.
• Monitor quota usage to prevent unexpected costs.
• Use environment variables in production environments.

Contributing

1. Fork the repository.
2. Create a feature branch (git checkout -b feature/amazing-feature).
3. Test your changes with python test_server.py.
4. Commit your changes (git commit -m 'Add amazing feature').
5. Push to the branch (git push origin feature/amazing-feature).
6. Open a Pull Request.

Development Notes

This project was developed using:

• Incremental methodology - One function at a time.
• Test - driven development - Each function tested before integration.
• User collaboration - Continuous feedback and approval gates.
• Backup protocols - Safe development with rollback capabilities.

See documents/testing.md for detailed development and testing procedures.

Troubleshooting

Common Issues

"API key not found" error:

• Ensure credentials.yml exists with correct format.
• Check file permissions.
• Verify API key is valid and not restricted.

"Quota exceeded" error:

• Check your Google Cloud Console quota usage.
• Consider upgrading quota or optimizing requests.
• Use caching for frequently accessed data.

"Video not found" error:

• Verify the video ID or URL is correct.
• Check if video is private or restricted.
• Ensure video hasn't been deleted.

MCP connection issues:

• Verify Python path in configuration.
• Check that all dependencies are installed.
• Restart your MCP client after configuration changes.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Built using the Model Context Protocol.
• Powered by YouTube Data API v3.
• Developed with FastMCP.

Ready to supercharge your AI assistant with YouTube capabilities? Get started today! 🚀