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

Verify project structure:

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

Deploy to Dedalus:

dedalus deploy . --name "youtube-mcp"

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

Entry Point (pyproject.toml): Defines main script that points to src.main:main
MCP Server (src/main.py): FastMCP instance with YouTube search tool
Search Logic (src/search.py): YouTube API integration with pagination
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

Query Optimization: Use specific queries for better results
Result Limits: Start with smaller max_results for faster responses
Language Codes: Use ISO 639-1 codes (e.g., "en", "es", "fr")
Error Handling: Always handle potential errors in client code
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

Support

For issues specific to:

Dedalus deployment: Check Dedalus Docs
MCP protocol: See MCP Spec
This server: Open an issue in the repository