youtube-mcp-server

OriShmila/youtube-mcp-server

3.2

If you are the rightful owner of youtube-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

A Model Context Protocol (MCP) server that provides comprehensive YouTube integration with video search, detailed video information retrieval, and transcript fetching capabilities.

Tools
3
Resources
0
Prompts
0

YouTube MCP Server

A Model Context Protocol (MCP) server that provides comprehensive YouTube integration with video search, detailed video information retrieval, and transcript fetching capabilities.

Features

  • šŸ” Video Search: Search YouTube videos with pagination support
  • šŸ“¹ Video Details: Get comprehensive video information including statistics, content details, and metadata
  • šŸ“ Transcript Fetching: Real transcript extraction with intelligent language prioritization
  • šŸŒ Multi-language Support: Automatic language detection and fallback for transcripts
  • āš” Async Performance: Built with async/await for optimal performance
  • šŸ”’ Input/Output Validation: Complete schema validation with detailed error reporting

Tools

1. search_videos

Search for videos on YouTube with flexible pagination.

Parameters:

  • query (string, required): Search query for finding videos
  • pageToken (string, optional): Token for pagination to get next/previous page results

Example:

{
  "query": "python programming tutorial",
  "pageToken": "CAUQAA"
}

Returns: Search results with video snippets and pagination tokens

2. get_videos

Get detailed information about specific YouTube videos.

Parameters:

  • ids (array, required): List of video IDs to retrieve (max 50)
  • parts (array, optional): Parts of video data to retrieve
    • Available parts: snippet, contentDetails, statistics, status, player, recordingDetails, fileDetails, processingDetails, suggestions, liveStreamingDetails, localizations, topicDetails
    • Default: ["snippet"]

Example:

{
  "ids": ["dQw4w9WgXcQ", "9bZkp7q19f0"],
  "parts": ["snippet", "contentDetails", "statistics"]
}

Returns: Comprehensive video data including duration, view counts, like counts, descriptions, and more

3. get_video_transcript

Extract video transcripts with intelligent language handling.

Parameters:

  • videoId (string, required): YouTube video ID
  • language (string, optional): Preferred language code (e.g., 'en', 'es', 'fr')

Language Priority:

  1. Requested language (if specified)
  2. English (fallback)
  3. Manual transcripts (preferred over auto-generated)
  4. Any available transcript

Example:

{
  "videoId": "dQw4w9WgXcQ",
  "language": "en"
}

Returns: Transcript with text segments, precise timestamps, and language metadata

Installation

Prerequisites

  1. YouTube Data API v3 Key:
    • Visit Google Cloud Console
    • Create a new project or select an existing one
    • Enable YouTube Data API v3
    • Create credentials (API Key)
    • Copy the API key for configuration

Setup

  1. Install the server:

    git clone <repository-url>
cd youtube-mcp-server
uv sync

  2. Configure environment:

    cp .env.example .env
# Edit .env and add your YouTube API key:
# YOUTUBE_API_KEY=your_actual_api_key_here

  3. Test installation:

    uv run python test_server.py

Claude Desktop Integration

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "youtube": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/yourusername/youtube-mcp-server",
        "youtube-mcp-server"
      ],
      "env": {
        "YOUTUBE_API_KEY": "your_youtube_api_key_here"
      }
    }
  }
}

Usage Examples

Basic Video Search

# Search for Python tutorials
result = await search_videos("python programming tutorial")

Get Video Details

# Get comprehensive video information
result = await get_videos(
    ids=["dQw4w9WgXcQ"], 
    parts=["snippet", "contentDetails", "statistics"]
)

Fetch Transcript

# Get transcript in preferred language
result = await get_video_transcript("dQw4w9WgXcQ", language="en")

API Rate Limits

The YouTube Data API v3 has the following quota limits:

  • Default quota: 10,000 units per day
  • Search requests: 100 units each
  • Video details: 1 unit per video
  • Transcript requests: No additional quota cost (uses separate API)

Typical usage:

  • Video search + details: ~110 units (allows ~90 searches/day)
  • Transcript fetching: No quota impact

Development

Project Structure

youtube-mcp-server/
ā”œā”€ā”€ youtube_mcp_server/
ā”‚   ā”œā”€ā”€ __init__.py
ā”‚   ā”œā”€ā”€ __main__.py
ā”‚   ā”œā”€ā”€ server.py          # MCP server implementation
ā”‚   ā”œā”€ā”€ handlers.py        # Tool function implementations
ā”‚   ā””ā”€ā”€ tools.json         # Tool schema definitions
ā”œā”€ā”€ test_cases.json        # Comprehensive test cases
ā”œā”€ā”€ test_server.py         # Test suite with schema validation
ā”œā”€ā”€ main.py               # Development entry point
ā”œā”€ā”€ pyproject.toml        # Project configuration
ā””ā”€ā”€ README.md

Running Tests

# Run comprehensive test suite
uv run python test_server.py

# Run the server locally
uv run python main.py

Adding Features

  1. Define tool schema in youtube_mcp_server/tools.json
  2. Implement function in youtube_mcp_server/handlers.py
  3. Update mapping in TOOL_FUNCTIONS
  4. Add test cases in test_cases.json
  5. Run tests to validate

Error Handling

The server provides comprehensive error handling:

  • šŸ”‘ API Key Issues: Clear messages for missing/invalid YouTube API keys
  • šŸ“Š Quota Management: Informative messages about API quota limits
  • āœ… Input Validation: Detailed validation errors for incorrect parameters
  • šŸŒ Network Resilience: Graceful handling of connection issues
  • šŸ” Schema Validation: Full input/output validation with detailed error messages

Technical Details

Dependencies

  • MCP Framework: mcp>=1.6.0 for Model Context Protocol support
  • Google API Client: google-api-python-client>=2.0.0 for YouTube Data API
  • Transcript API: youtube-transcript-api>=0.6.0 for transcript extraction
  • Environment: python-dotenv>=1.0.0 for configuration management
  • Validation: jsonschema>=4.0.0 for schema validation

Performance

  • Async Architecture: All operations use async/await for optimal performance
  • Connection Pooling: Efficient HTTP connection management
  • Error Recovery: Automatic retry logic for transient failures
  • Schema Caching: Tool schemas loaded once at startup

Security

  • Environment Variables: API keys stored securely in environment
  • Input Sanitization: All inputs validated against strict schemas
  • Rate Limiting: Built-in respect for YouTube API rate limits
  • Error Isolation: Detailed error messages without exposing internals

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Implement your changes with tests
  4. Ensure all tests pass: uv run python test_server.py
  5. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

  • Documentation: Check test cases in test_cases.json for usage examples
  • Validation: Run uv run python test_server.py to validate your setup
  • API Reference: YouTube Data API v3 Documentation
  • Issues: Open GitHub issues for bugs or feature requests

Built with ā¤ļø using the Model Context Protocol framework.