YouTube MCP Server

A Model Context Protocol (MCP) server that provides YouTube search capabilities for AI assistants. Designed for remote deployment on Dedalus platform with HTTP transport.

Features

• 🔍 YouTube Search: Search YouTube videos with rich metadata

• 🌍 Multi-language Support: Search in any language (en, es, fr, de, etc.)

• 📊 Rich Metadata: Get video titles, channels, views, duration, and more

• 🚀 Remote Ready: HTTP server mode for Dedalus deployment

• 🛠️ Local Development: STDIO mode for testing

Quick Start

Installation

# Install uv package manager (if not already installed)
brew install uv  # macOS
# or: pip install uv

# Install dependencies
uv sync

Local Testing (STDIO mode)

# Run server in STDIO mode
uv run main --stdio

# Or run tests
uv run python test_mcp_tools.py

Remote HTTP Server (Dedalus deployment)

# Run HTTP server locally
uv run main --port 8080

# The server will start at:
# - Health check: http://localhost:8080/health
# - SSE endpoint: http://localhost:8080/sse

Deploy to Dedalus

Prerequisites

• Dedalus account and CLI installed

• Repository pushed to GitHub

Deployment Steps

1. Verify project structure:

your-project/
├── pyproject.toml      # Package configuration with entry point
├── src/
│   └── main.py        # MCP server implementation
└── .env               # Optional: local environment variables

2. Deploy to Dedalus:

dedalus deploy . --name "youtube-mcp"

3. Use in Dedalus workflows:

from dedalus_labs import AsyncDedalus, DedalusRunner

async def search_youtube_videos():
    client = AsyncDedalus(api_key="your-key")
    runner = DedalusRunner(client)

    result = await runner.run(
        input="Search YouTube for Python tutorials",
        model="openai/gpt-4",
        mcp_servers=["your-org/youtube-mcp"]
    )

    print(result.final_output)

Available Tools

search_youtube(query, lang="en", max_results=30)

Search YouTube and return video results with metadata.

Parameters:

• query (str): Search query (e.g., "machine learning tutorial")

• lang (str): Language code (default: "en")

• max_results (int): Max results to return, up to 100 (default: 30)

Returns: List of dictionaries with:

• video_id: YouTube video ID

• video_title: Full video title

• channel_id: Channel ID

• channel_name: Channel display name

• channel_link: Channel URL path

• view_count: Formatted view count (e.g., "1.2M views")

• published_date: Publish time (e.g., "2 days ago")

• duration: Video duration (e.g., "10:23")

Example:

# Search for Python tutorials
results = search_youtube("Python tutorial", lang="en", max_results=10)

# Access results
for video in results:
    print(f"{video['video_title']} - {video['channel_name']}")
    print(f"Views: {video['view_count']} | Duration: {video['duration']}")

Architecture

Project Structure

youtube-mcp-server/
├── pyproject.toml          # Package config with entry point
├── src/
│   ├── __init__.py
│   ├── main.py            # MCP server (FastMCP)
│   └── search.py          # YouTube search logic
├── test_mcp_tools.py      # Functional tests
├── .env.example           # Environment variable template
└── README.md              # This file

How It Works

1. Entry Point (pyproject.toml): Defines main script that points to src.main:main

2. MCP Server (src/main.py): FastMCP instance with YouTube search tool

3. Search Logic (src/search.py): YouTube API integration with pagination

4. Transport Mode: Automatically selects HTTP (remote) or STDIO (local)

Transport Modes

The server automatically selects the appropriate transport:

• HTTP Mode (Production): When PORT environment variable is set or --port is specified

• STDIO Mode (Development): Default when no port is configured

Configuration

Environment Variables

• PORT: HTTP server port (default: 8080)

• HOST: HTTP server host (default: 0.0.0.0)

Command-Line Arguments

# Start with custom port
uv run main --port 9000

# Force STDIO mode
uv run main --stdio

# Custom host
uv run main --host 127.0.0.1 --port 8080

Development

Running Tests

# Run functional tests
uv run python test_mcp_tools.py

# Test server import
uv run python -c "from src.main import mcp; print('OK')"

# Test entry point
uv run main --help

Standalone Search Script

The YouTube search functionality can also be run standalone:

# Search from command line
uv run python src/search.py "machine learning" --max-results 10

# With language option
uv run python src/search.py "Python tutorial" --lang es --max-results 5

Technical Details

Dependencies

• mcp>=1.16.0: Model Context Protocol SDK

• httpx: HTTP client for API requests

• pydantic: Data validation

• python-dotenv: Environment variable management

• ua-generator: User agent generation

YouTube API

This server uses the YouTube internal API (youtubei) for search:

• No API key required

• Automatic pagination handling

• Rate limiting handled by YouTube

• Returns up to 100 results per query

Error Handling

• Graceful handling of network errors

• Retry logic for transient failures

• Validation of input parameters

• Clear error messages

Troubleshooting

Server won't start

# Check imports
uv run python -c "from src.main import mcp; print('OK')"

# Verify dependencies
uv sync

# Check for port conflicts
lsof -i :8080  # macOS/Linux

No search results

• Check internet connection

• Verify query is valid

• Try with fewer max_results

• Check YouTube API status

Dedalus deployment issues

• Ensure pyproject.toml is configured correctly

• Verify main.py exists in project root

• Check src/main.py has proper imports

• Review Dedalus deployment logs

Best Practices

1. Query Optimization: Use specific queries for better results

2. Result Limits: Start with smaller max_results for faster responses

3. Language Codes: Use ISO 639-1 codes (e.g., "en", "es", "fr")

4. Error Handling: Always handle potential errors in client code

5. Rate Limiting: Be mindful of request frequency

Examples

Basic Search

results = search_youtube("Python tutorial", max_results=5)
for video in results:
    print(f"Title: {video['video_title']}")
    print(f"URL: https://youtube.com/watch?v={video['video_id']}")

Multi-language Search

# Search in Spanish
results_es = search_youtube("tutorial Python", lang="es", max_results=10)

# Search in French
results_fr = search_youtube("tutoriel Python", lang="fr", max_results=10)

Channel Discovery

# Search for a specific channel
results = search_youtube("Andrej Karpathy", max_results=30)

# Filter by channel name
karpathy_videos = [
    v for v in results
    if "Andrej Karpathy" in v['channel_name']
]

Contributing

This is a reference implementation for Dedalus MCP servers. Feel free to:

• Report issues

• Suggest improvements

• Fork and customize

License

This project is provided as an example. Modify and use as needed.

Resources

• Dedalus Documentation

• MCP Specification

• FastMCP Documentation

Support

For issues specific to:

• Dedalus deployment: Check Dedalus Docs

• MCP protocol: See MCP Spec

• This server: Open an issue in the repository