# YtMCP - YouTube Model Context Protocol Server
[](https://www.python.org/downloads/)
[](https://github.com/modelcontextprotocol)
[](https://opensource.org/licenses/MIT)
[](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:**
[](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**
[](https://github.com/utkarshchaudhary009/ytmcp)
</div>
