YouTube Search MCP Server

# 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 ```bash # Install uv package manager (if not already installed) brew install uv # macOS # or: pip install uv # Install dependencies uv sync ``` ### Local Testing (STDIO mode) ```bash # Run server in STDIO mode uv run main --stdio # Or run tests uv run python test_mcp_tools.py ``` ### Remote HTTP Server (Dedalus deployment) ```bash # 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**: ```bash dedalus deploy . --name "youtube-mcp" ``` 3. **Use in Dedalus workflows**: ```python 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:** ```python # 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 ```bash # 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 ```bash # 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: ```bash # 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 ```bash # 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 ```python 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 ```python # 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 ```python # 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](https://docs.dedaluslabs.ai/) - [MCP Specification](https://modelcontextprotocol.io/) - [FastMCP Documentation](https://github.com/modelcontextprotocol/python-sdk) ## Support For issues specific to: - **Dedalus deployment**: Check [Dedalus Docs](https://docs.dedaluslabs.ai/) - **MCP protocol**: See [MCP Spec](https://modelcontextprotocol.io/) - **This server**: Open an issue in the repository