# 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