# YtMCP - YouTube Model Context Protocol Server

[![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)
[![MCP](https://img.shields.io/badge/MCP-1.25.0+-green.svg)](https://github.com/modelcontextprotocol)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Deploy to Render](https://img.shields.io/badge/deploy-render-46E3B7.svg)](https://render.com)

**YtMCP** is a production-grade Model Context Protocol (MCP) server providing comprehensive, read-only access to YouTube data through 16 specialized tools. Designed for both **local development** (STDIO) and **cloud deployment** (HTTPS on Render), it combines multiple battle-tested libraries to deliver robust YouTube intelligence for LLM applications.

---

## 📋 Table of Contents

- [Features](#-features)
- [Quick Start](#-quick-start)
  - [Local Development (STDIO)](#local-development-stdio)
  - [Production Deployment (Render)](#production-deployment-render)
- [Tool Categories](#-tool-categories)
- [Architecture](#-architecture)
- [Configuration](#-configuration)
  - [MCP Clients](#mcp-clients)
  - [Environment Variables](#environment-variables)
- [API Reference](#-api-reference)
- [Development](#-development)
- [Deployment Guide](#-deployment-guide)
- [Security & Compliance](#-security--compliance)
- [Troubleshooting](#-troubleshooting)
- [Contributing](#-contributing)
- [License](#-license)

---

## ✨ Features

### 🔍 **Category A: Core Discovery (5 Tools)**
- **`search_videos`** - Basic keyword search with customizable limits
- **`search_filtered`** - Advanced search with filters (upload date, duration, sort)
- **`get_trending_videos`** - Fetch current trending videos
- **`find_channels`** - Search for channels by name or topic
- **`find_playlists`** - Discover playlists by keyword

### 🎥 **Category B: Video Intelligence (5 Tools)**
- **`get_transcript`** - Extract time-synced transcripts/subtitles (CRITICAL for content analysis)
- **`get_video_metadata`** - Comprehensive video data (views, tags, description, likes, duration)
- **`get_video_chapters`** - Extract video chapters/key moments
- **`get_thumbnail`** - High-resolution thumbnail URLs (all qualities)
- **`get_comments`** - Fetch top comments (rate-limited for safety)

### 📊 **Category C: Channel & Playlist Forensics (5 Tools)**
- **`get_channel_videos`** - List channel videos with sorting (newest, oldest, popular)
- **`get_channel_shorts`** - List YouTube Shorts from a channel
- **`get_channel_streams`** - List live streams (past and present)
- **`get_playlist_items`** - Flatten playlist contents
- **`get_channel_about`** - Channel description and statistics

### 🛠️ **Category D: Utilities (1 Tool)**
- **`get_audio_stream_url`** - Get direct audio stream URLs

---

## 🚀 Quick Start

### Local Development (STDIO)

**Prerequisites:**
- Python 3.13+
- [UV package manager](https://github.com/astral-sh/uv) (recommended) or pip

**Installation:**

```bash
# Clone the repository
git clone https://github.com/utkarshchaudhary009/ytmcp.git
cd ytmcp

# Install with UV (recommended)
uv sync

# OR install with pip
pip install -e .
```

**Run the server:**

```bash
# Using UV
uv run ytmcp

# OR using pip
ytmcp
```

The server will start in STDIO mode, ready to accept MCP client connections.

---

### Production Deployment (Render)

**One-Click Deploy:**

[![Deploy to Render](https://render.com/images/deploy-to-render-button.svg)](https://render.com/deploy)

**Manual Deployment:**

1. **Fork this repository**

2. **Create a new Web Service on Render:**
   - Go to [Render Dashboard](https://dashboard.render.com/)
   - Click "New +" → "Web Service"
   - Connect your GitHub repository

3. **Configure the service:**
   ```yaml
   Name: ytmcp
   Environment: Python 3
   Build Command: pip install -e .
   Start Command: ytmcp --transport streamable-http --host 0.0.0.0 --port $PORT
   ```

4. **Set environment variables (optional):**
   ```
   FASTMCP_LOG_LEVEL=INFO
   ```

5. **Deploy** - Render will automatically deploy your MCP server with HTTPS

**Your server will be available at:** `https://ytmcp-<random>.onrender.com`

---

## 🏗️ Architecture

```
ytmcp/
├── src/
│   └── ytmcp/
│       ├── __init__.py
│       ├── server.py              # Main FastMCP server with health check
│       ├── middleware/
│       │   ├── __init__.py
│       │   └── rate_limiter.py    # Global rate limiting (0.75s delay)
│       └── tools/
│           ├── __init__.py
│           ├── search.py          # Category A: Search tools
│           ├── video.py           # Category B: Video intelligence
│           ├── channel.py         # Category C: Channel forensics
│           └── utils.py           # Category D: Utilities
├── examples/                      # MCP client configurations
├── research/                      # Library research & feasibility docs
├── render.yaml                    # Render deployment config
├── Procfile                       # Process definition
├── runtime.txt                    # Python version specification
├── pyproject.toml                 # Project metadata & dependencies
└── README.md
```

### 🧠 **Design Principles**

1. **Rate Limiting First** - Global 0.75s delay prevents IP bans
2. **Library Specialization:**
   - `scrapetube` → Fast channel/playlist listing
   - `youtube-search-python` → Search & filtering
   - `yt-dlp` → Comprehensive metadata extraction
   - `youtube-transcript-api` → Transcript fetching
3. **LLM-Optimized Output** - All responses in Markdown
4. **Dual-Mode Operation** - STDIO for local, HTTPS for production
5. **Health Monitoring** - `/health` endpoint for load balancers

---

## ⚙️ Configuration

### MCP Clients

#### **Gemini CLI** (`.gemini/mcp_config.json`)
```json
{
  "mcpServers": {
    "ytmcp-local": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/ytmcp", "ytmcp"],
      "description": "YouTube MCP (Local)"
    },
    "ytmcp-prod": {
      "url": "https://your-ytmcp.onrender.com/mcp",
      "description": "YouTube MCP (Production)"
    }
  }
}
```

#### **Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`)
```json
{
  "mcpServers": {
    "ytmcp": {
      "command": "uv",
      "args": ["--directory", "/path/to/ytmcp", "run", "ytmcp"]
    }
  }
}
```

#### **Cursor** (`.cursor/mcp.json`)
```json
{
  "mcpServers": {
    "ytmcp": {
      "command": "uv",
      "args": ["--directory", "/path/to/ytmcp", "run", "ytmcp"]
    }
  }
}
```

#### **VS Code Continue** (`~/.continue/config.json`)
```json
{
  "mcpServers": {
    "ytmcp": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/ytmcp", "ytmcp"]
    }
  }
}
```

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `FASTMCP_LOG_LEVEL` | `INFO` | Logging level (`DEBUG`, `INFO`, `WARNING`, `ERROR`) |
| `FASTMCP_HOST` | `127.0.0.1` | Host to bind (HTTP transports) |
| `FASTMCP_PORT` | `8000` | Port to bind (HTTP transports) |
| `PORT` | - | Render auto-assigns this (production) |

---

## 📚 API Reference

### Example Tool Calls

#### Search for Videos
```python
search_videos_tool(
    query="python tutorial",
    limit=10
)
```

**Returns:** Markdown-formatted list with titles, channels, views, URLs

---

#### Get Video Transcript
```python
get_transcript_tool(
    video_id="dQw4w9WgXcQ",  # Or full URL
    languages="en,de"         # Fallback languages
)
```

**Returns:** Time-synced transcript with `[MM:SS]` timestamps

---

#### Analyze Channel
```python
get_channel_videos_tool(
    channel_id="@fireship",   # Supports @handle, ID, or URL
    sort_by="popular",
    limit=20
)
```

**Returns:** Sorted video list with metadata

---

#### Extract Metadata
```python
get_video_metadata_tool(
    video_id="https://youtube.com/watch?v=dQw4w9WgXcQ"
)
```

**Returns:** Comprehensive metadata (views, likes, description, tags, etc.)

---

## 🛠️ Development

### Setup Development Environment

```bash
# Install with dev dependencies
uv sync --dev

# Run tests
uv run pytest

# Type checking
uv run mypy src/

# Linting
uv run ruff check src/
```

### Running Different Transports

```bash
# STDIO (for MCP clients)
uv run ytmcp

# SSE (for web clients)
uv run ytmcp --transport sse --port 8000

# StreamableHTTP (for production)
uv run ytmcp --transport streamable-http --host 0.0.0.0 --port 8080
```

### Code Structure

Each tool follows this pattern:

```python
from ..middleware.rate_limiter import rate_limiter

@rate_limiter  # Automatic rate limiting
async def tool_name(param: str) -> str:
    """Tool description."""
    # 1. Extract/validate IDs
    # 2. Define library options
    # 3. Fetch data in thread pool
    # 4. Format as Markdown
    # 5. Return LLM-optimized output
```

---

## 🚢 Deployment Guide

### Render (Recommended)

**Advantages:**
- Free tier with 750 hours/month
- Auto-SSL (HTTPS)
- Auto-restart on crashes
- GitHub integration for auto-deploy

**Steps:**

1. Push code to GitHub
2. Connect Render to your repo
3. Use `render.yaml` configuration (included)
4. Deploy

**Health Check:** `https://your-app.onrender.com/health`

**MCP Endpoint:** `https://your-app.onrender.com/mcp`

---

### Heroku

```bash
# Login to Heroku
heroku login

# Create app
heroku create ytmcp

# Deploy
git push heroku main

# Set environment
heroku config:set FASTMCP_LOG_LEVEL=INFO
```

---

### Railway

1. Connect GitHub repo
2. Add environment variables
3. Deploy with Procfile

---

### Docker (Self-Hosted)

```dockerfile
FROM python:3.13-slim

WORKDIR /app
COPY . .

RUN pip install -e .

EXPOSE 8080
CMD ["ytmcp", "--transport", "streamable-http", "--host", "0.0.0.0", "--port", "8080"]
```

```bash
docker build -t ytmcp .
docker run -p 8080:8080 ytmcp
```

---

## 🔒 Security & Compliance

- **Read-Only:** No write operations to YouTube
- **No API Keys:** Uses scraping libraries (check YouTube ToS for commercial use)
- **Privacy:** No user authentication or tracking
- **Rate Limiting:** Prevents abuse and IP bans
- **Transport Security:** HTTPS in production, SSH for STDIO

**⚠️ YouTube Terms of Service:**
This server uses scraping libraries that bypass official YouTube API quotas. Review [YouTube's ToS](https://www.youtube.com/t/terms) before deploying for commercial purposes.

---

## 🐛 Troubleshooting

### Server Won't Start

**Check Python version:**
```bash
python --version  # Should be 3.13+
```

**Reinstall dependencies:**
```bash
uv sync --reinstall
```

---

### Rate Limiting Too Aggressive

Adjust in `src/ytmcp/middleware/rate_limiter.py`:

```python
rate_limiter = RateLimiter(delay_seconds=0.5)  # Faster (risky)
```

---

### Render Deployment Fails

**Check build logs:**
- Ensure Python 3.13 is available
- Verify `runtime.txt` specifies `python-3.13`

**Common fix:**
```yaml
buildCommand: pip install --upgrade pip && pip install -e .
```

---

### MCP Client Can't Connect

**Local (STDIO):**
- Ensure server is running: `uv run ytmcp`
- Check client config paths are absolute
- Restart MCP client

**Production (HTTPS):**
- Verify server health: `curl https://your-app.onrender.com/health`
- Check MCP endpoint: `https://your-app.onrender.com/mcp`
- Ensure HTTPS (not HTTP)

---

## 🤝 Contributing

Contributions welcome! Please:

1. Review `/research` for library capabilities
2. Follow existing tool patterns
3. Maintain rate limiting
4. Format outputs in Markdown
5. Update documentation

**Development Workflow:**

```bash
# Fork and clone
git clone https://github.com/utkarshchaudhary009/ytmcp.git

# Create feature branch
git checkout -b feature/new-tool

# Make changes and test
uv run ytmcp

# Submit PR
```

---

## 📄 License

MIT License - See [LICENSE](LICENSE) file

---

## 🙏 Acknowledgments

Built with these excellent libraries:
- [yt-dlp](https://github.com/yt-dlp/yt-dlp) - Video metadata extraction
- [scrapetube](https://github.com/dermasmid/scrapetube) - Channel scraping
- [youtube-search-python](https://github.com/alexmercerind/youtube-search-python) - Search
- [youtube-transcript-api](https://github.com/jdepoix/youtube-transcript-api) - Transcripts
- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) - Protocol foundation

---

## 📞 Support

- **Issues:** [GitHub Issues](https://github.com/utkarshchaudhary009/ytmcp/issues)
- **Discussions:** [GitHub Discussions](https://github.com/utkarshchaudhary009/ytmcp/discussions)
- **Documentation:** See `/research` for design decisions

---

<div align="center">

**Built with ❤️ for the LLM ecosystem**

[![Star on GitHub](https://img.shields.io/github/stars/utkarshchaudhary009/ytmcp?style=social)](https://github.com/utkarshchaudhary009/ytmcp)

</div>