YouTube MCP Server

Model Contex Protocol (MCP) server that enables AI models to interact with YouTube content through a standardized interface. This server provides a set of tools for video search, content analysis, comment processing, and more.

🌟 Features

• 🔍 Video Search & Discovery

  • Search YouTube videos
  • Get trending videos
  • Find related content
  • Channel information

• 📊 Content Analysis

  • Detailed video information
  • Channel statistics
  • Video transcripts
  • Comprehensive summaries

• 💬 Social Features

  • Comment retrieval
  • Comment analysis
  • User interaction data

🚀 Quick Start

Prerequisites

1. Installing Python

macOS:

# Using Homebrew (recommended)
brew install python@3.11

# Verify installation
python3 --version  # Should show Python 3.11.x

Linux (Ubuntu/Debian):

# Update package list
sudo apt update

# Install Python
sudo apt install python3.11 python3.11-venv

# Verify installation
python3 --version  # Should show Python 3.11.x

Windows:

1. Download Python installer from python.org
2. Run the installer
3. Check "Add Python to PATH" during installation
4. Open Command Prompt and verify:

python --version  # Should show Python 3.11.x

2. Installing uv

macOS/Linux:

# Install uv using the official installer
curl -LsSf https://astral.sh/uv/install.sh | sh

# Verify installation
uv --version

Windows (PowerShell):

# Install uv using the official installer
(Invoke-WebRequest -Uri "https://astral.sh/uv/install.ps1" -UseBasicParsing).Content | pwsh -Command -

# Verify installation
uv --version

Alternative Installation Methods:

Using pip (if you prefer):

# Install uv using pip
pip install uv

# Verify installation
uv --version

3. Setting Up Google Cloud Credentials

1. Create a Google Cloud Project:

   # Go to Google Cloud Console
   https://console.cloud.google.com
   
   # Click on "Select a Project" at the top
   # Click "New Project"
   # Name it (e.g., "youtube-mcp-server")
   # Click "Create"
   

2. Enable YouTube Data API:

   # In the Google Cloud Console:
   # 1. Go to "APIs & Services" > "Library"
   # 2. Search for "YouTube Data API v3"
   # 3. Click "Enable"
   

3. Create OAuth 2.0 Credentials:

   # In the Google Cloud Console:
   # 1. Go to "APIs & Services" > "Credentials"
   # 2. Click "Create Credentials" > "OAuth client ID"
   # 3. Select "Desktop app" as application type
   # 4. Name it (e.g., "YouTube MCP Client")
   # 5. Click "Create"
   

4. Download and Store Credentials:

   # 1. After creating credentials, click "Download JSON"
   # 2. Rename the downloaded file to 'credentials.json'
   # 3. Move it to your project root:
   mv ~/Downloads/client_secret_*.json ./credentials.json
   
   # Verify the file exists and has correct permissions
   ls -l credentials.json  # Should show -rw------- (readable only by you)
   

5. First-time Authentication:

   # Run the server once to authenticate
   python mcp_videos.py
   
   # This will:
   # 1. Open your browser
   # 2. Ask you to sign in to Google
   # 3. Grant permissions to the application
   # 4. Create a token.pickle file (automatically ignored by git)
   

⚠️ Important Security Notes:

• Never commit credentials.json or token.pickle to git
• Keep your credentials secure and don't share them
• If credentials are compromised:
  1. Go to Google Cloud Console
  2. Delete the compromised credentials
  3. Create new credentials
  4. Update your local credentials.json

Installation

1. Clone the repository:

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

2. Create and activate a virtual environment:

# Create virtual environment
python -m venv .venv

# Activate virtual environment
# On macOS/Linux:
source .venv/bin/activate
# On Windows (Command Prompt):
.venv\Scripts\activate
# On Windows (PowerShell):
.venv\Scripts\Activate.ps1

3. Install dependencies using uv:

# Install project in editable mode
uv pip install -e .

# If you encounter any SSL errors on macOS, you might need to:
export SSL_CERT_FILE=/etc/ssl/cert.pem

4. Set up YouTube API credentials:
   • Go to Google Cloud Console
   • Create a new project
   • Enable YouTube Data API v3
   • Create credentials (OAuth 2.0 Client ID)
   • Download the credentials and save as client_secrets.json

Development Setup

For development, you might want to install additional tools:

# Install development dependencies
uv pip install -e ".[dev]"

# Install pre-commit hooks
pre-commit install

Configuration

1. Create a .env file in the project root:

# Required environment variables
YOUTUBE_API_KEY=your_api_key_here

# Optional configuration
YOUTUBE_API_QUOTA_LIMIT=10000  # Daily quota limit
YOUTUBE_API_REGION=US          # Default region

2. Verify your setup:

# Check if credentials are properly set up
ls -l credentials.json  # Should exist and be readable
ls -l .env             # Should exist and be readable
ls -l token.pickle     # Should exist after first authentication

# Test the server
python mcp_videos.py

🛠️ Usage

Starting the Server

python mcp_videos.py

Available Tools

1. Search Videos

@mcp.tool()
async def get_videos(search: str, max_results: int)

2. Get Video Info

@mcp.tool()
async def get_video_info(video_id: str)

3. Get Channel Details

@mcp.tool()
async def get_channel_details(channel_id: str)

4. Get Video Comments

@mcp.tool()
async def get_video_comments_tool(video_id: str, max_results: int = 100)

5. Get Trending Videos

@mcp.tool()
async def get_trending_videos_tool(region_code: str = "US", max_results: int = 50)

6. Get Related Videos

@mcp.tool()
async def get_related_videos_tool(video_id: str, max_results: int = 25)

7. Summarize Video

@mcp.tool()
async def summarize_video(video_id: str, include_comments: bool = True)

8. Generate Video Flash Cards

@mcp.tool()
async def generate_video_flashcards(
    video_id: str,
    max_cards: int = 10,
    categories: Optional[List[str]] = None,
    difficulty: Optional[str] = None
)

This tool generates educational flash cards from video content:

• Creates different types of cards (Fill in the blank, Q&A, Definition)
• Includes timestamps for video reference
• Categorizes cards by type and difficulty
• Provides card statistics

Example usage:

# Generate 15 flash cards from a video
cards = generate_video_flashcards(
    video_id="dQw4w9WgXcQ",
    max_cards=15,
    categories=["Q&A", "Definition"],
    difficulty="Medium"
)

# Generate all types of cards
cards = generate_video_flashcards(
    video_id="dQw4w9WgXcQ",
    max_cards=20
)

Card Types:

• Fill in the blank: Tests recall of specific terms or concepts
• Q&A: Questions about key points in the video
• Definition: Explains important concepts

Difficulty Levels:

• Easy: Basic recall and understanding
• Medium: Application of concepts
• Hard: Complex concepts and relationships

9. Generate Video Quiz

@mcp.tool()
async def generate_video_quiz(video_id: str) -> str

This tool generates a comprehensive quiz from video content:

• Creates multiple choice questions
• Generates true/false statements
• Includes fill-in-the-blank questions
• Uses video metadata, transcript, and description
• Provides answers and explanations

Example usage:

# Generate a quiz from a video
quiz = generate_video_quiz("dQw4w9WgXcQ")

Quiz Features:

• Multiple Choice Questions

  • Based on video content
  • Includes video metadata
  • Tests understanding of key concepts

• True/False Questions

  • Tests factual knowledge
  • Based on video statistics
  • Verifies understanding of claims

• Fill in the Blank

  • Tests recall of specific terms
  • Uses transcript content
  • Focuses on key concepts

Quiz Format:

=== Video Quiz ===
Title: [Video Title]
Channel: [Channel Name]
URL: [Video URL]

Question 1 (Multiple Choice):
[Question text]
1. [Option 1]
2. [Option 2]
3. [Option 3]
4. [Option 4]

Answer: [Correct answer]
------------------

Question 2 (True/False):
[Statement]

Answer: True/False
------------------

Question 3 (Fill in the blank):
[Question with blank]

Answer: [Correct answer]
------------------

The quiz tool:

• Generates exactly 10 questions
• Mixes different question types
• Includes video context
• Provides immediate feedback
• Uses video metadata for questions
• Incorporates transcript content
• Tests different levels of understanding

📊 Architecture

The project follows a modular architecture:

graph TD
    A[LLM Client] --> B[MCP Client]
    B --> C[MCP Server]
    C --> D[YouTube API]
    C --> E[Tool Registry]
    C --> F[Data Formatter]

    subgraph "Tools"
        E --> E1[Video Tools]
        E --> E2[Channel Tools]
        E --> E3[Comment Tools]
        E --> E4[Analysis Tools]
    end

🔧 Development

Project Structure

youtube-mcp-server/
├── mcp_videos.py          # Main server implementation
├── youtube_api.py         # YouTube API client
├── yt_helper.py          # Helper functions
├── requirements.txt       # Project dependencies
├── .env                  # Environment variables
├── .gitignore           # Git ignore rules
└── README.md            # This file

Adding New Tools

1. Create a new async function in mcp_videos.py
2. Decorate it with @mcp.tool()
3. Implement the tool logic
4. Add appropriate error handling
5. Update documentation

📝 API Documentation

Response Formats

1. Video Format

{
    "title": str,
    "channel_title": str,
    "duration": str,
    "description": str,
    "view_count": int,
    "like_count": int,
    "comment_count": int,
    "url": str,
    "published_at": str
}

2. Channel Format

{
    "title": str,
    "subscriber_count": int,
    "video_count": int,
    "view_count": int,
    "description": str,
    "published_at": str
}

3. Comment Format

{
    "author": str,
    "text": str,
    "like_count": int,
    "published_at": str
}

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

📄 License

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

🙏 Acknowledgments

• FastMCP for the MCP framework
• YouTube Data API for the API
• All contributors and users of this project

📞 Support

For support, please:

1. Check the documentation
2. Open an issue
3. Contact the maintainers

🔄 Updates

Stay updated with the project:

• Watch the repository
• Check the releases
• Follow the changelog

🔒 Security

Handling Sensitive Data

⚠️ IMPORTANT: Never commit sensitive files to the repository:

• token.pickle
• client_secrets.json
• .env files
• Any other credential files

These files are automatically ignored by .gitignore, but if you accidentally commit them:

1. Remove them from git tracking:

git rm --cached token.pickle
git rm --cached client_secrets.json

2. Revoke and regenerate any exposed credentials
3. Update your local .env file with new credentials
4. Never share or expose these files publicly

Best Practices

1. Always use environment variables for sensitive data
2. Keep credentials in .env file (already in .gitignore)
3. Regularly rotate API keys and tokens
4. Use OAuth 2.0 for authentication
5. Monitor GitHub's secret scanning alerts

🖥️ Claude Desktop Setup

1. Install Claude Desktop

1. Download Claude Desktop:

   • Visit Claude Desktop
   • Download the appropriate version for your OS:
     • macOS: .dmg file
     • Windows: .exe installer
     • Linux: .AppImage or .deb package

2. Install the Application:

   # macOS
   # 1. Open the .dmg file
   # 2. Drag Claude to Applications folder
   # 3. Open from Applications
   
   # Windows
   # 1. Run the .exe installer
   # 2. Follow the installation wizard
   # 3. Launch from Start Menu
   
   # Linux (Ubuntu/Debian)
   sudo dpkg -i claude-desktop_*.deb  # For .deb package
   # OR
   chmod +x Claude-*.AppImage         # For AppImage
   ./Claude-*.AppImage
   

2. Configure MCP Client

1. Open Claude Desktop Settings:

   • Click on the gear icon (⚙️) or
   • Use keyboard shortcut:
     • macOS: Cmd + ,
     • Windows/Linux: Ctrl + ,

2. Add MCP Configuration:

   • Navigate to "MCP Settings" or "Advanced Settings"
   • Add the following configuration:

   {
     "mcpServers": {
       "youtube_videos": {
         "command": "uv",
         "args": [
           "--directory",
           "<your base directory>/youtube-mcp-server",
           "run",
           "mcp_videos.py"
         ]
       }
     }
   }
   

3. Replace Path:

   • Replace <your base directory> with your actual project path

   • Example for different OS:

     // macOS/Linux
     "/Users/username/Documents/youtube-mcp-server"
     
     // Windows
     "C:\\Users\\username\\Documents\\youtube-mcp-server"
     

4. Verify Configuration:

   # Test the MCP server path
   cd "<your base directory>/youtube-mcp-server"
   uv run mcp_videos.py
   

3. Using Claude with MCP

1. Start Claude Desktop

2. Connect to MCP Server:

   • The server should start automatically
   • You'll see a connection status indicator
   • Available tools will be listed in the interface

3. Test the Connection:

   # Try a simple command
   get_videos("python programming", max_results=5)
   

Troubleshooting MCP Connection

1. Server Won't Start:

   # Check if the path is correct
   pwd  # Should show your project directory
   
   # Verify Python environment
   which python  # Should point to your virtual environment
   
   # Check uv installation
   uv --version
   

2. Connection Issues:

   • Verify the server is running
   • Check the configuration path
   • Ensure all dependencies are installed
   • Check the logs in Claude Desktop

3. Common Errors:

   # Path not found
   # Solution: Use absolute path in configuration
   
   # Permission denied
   # Solution: Check file permissions
   chmod +x mcp_videos.py
   
   # Module not found
   # Solution: Verify virtual environment
   source .venv/bin/activate  # or appropriate activation command