YtMCP - YouTube Model Context Protocol Server
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
- Quick Start
- Tool Categories
- Architecture
- Configuration
- API Reference
- Development
- Deployment Guide
- Security & Compliance
- Troubleshooting
- Contributing
- License
✨ Features
🔍 Category A: Core Discovery (5 Tools)
search_videos- Basic keyword search with customizable limitssearch_filtered- Advanced search with filters (upload date, duration, sort)get_trending_videos- Fetch current trending videosfind_channels- Search for channels by name or topicfind_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 momentsget_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 channelget_channel_streams- List live streams (past and present)get_playlist_items- Flatten playlist contentsget_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 (recommended) or pip
Installation:
# 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:
# 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:
Manual Deployment:
-
Fork this repository
-
Create a new Web Service on Render:
- Go to Render Dashboard
- Click "New +" → "Web Service"
- Connect your GitHub repository
-
Configure the service:
Name: ytmcp Environment: Python 3 Build Command: pip install -e . Start Command: ytmcp --transport streamable-http --host 0.0.0.0 --port $PORT -
Set environment variables (optional):
FASTMCP_LOG_LEVEL=INFO -
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
- Rate Limiting First - Global 0.75s delay prevents IP bans
- Library Specialization:
scrapetube→ Fast channel/playlist listingyoutube-search-python→ Search & filteringyt-dlp→ Comprehensive metadata extractionyoutube-transcript-api→ Transcript fetching
- LLM-Optimized Output - All responses in Markdown
- Dual-Mode Operation - STDIO for local, HTTPS for production
- Health Monitoring -
/healthendpoint for load balancers
⚙️ Configuration
MCP Clients
Gemini CLI (.gemini/mcp_config.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)
{
"mcpServers": {
"ytmcp": {
"command": "uv",
"args": ["--directory", "/path/to/ytmcp", "run", "ytmcp"]
}
}
}
Cursor (.cursor/mcp.json)
{
"mcpServers": {
"ytmcp": {
"command": "uv",
"args": ["--directory", "/path/to/ytmcp", "run", "ytmcp"]
}
}
}
VS Code Continue (~/.continue/config.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
search_videos_tool(
query="python tutorial",
limit=10
)
Returns: Markdown-formatted list with titles, channels, views, URLs
Get Video Transcript
get_transcript_tool(
video_id="dQw4w9WgXcQ", # Or full URL
languages="en,de" # Fallback languages
)
Returns: Time-synced transcript with [MM:SS] timestamps
Analyze Channel
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
get_video_metadata_tool(
video_id="https://youtube.com/watch?v=dQw4w9WgXcQ"
)
Returns: Comprehensive metadata (views, likes, description, tags, etc.)
🛠️ Development
Setup Development Environment
# 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
# 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:
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:
- Push code to GitHub
- Connect Render to your repo
- Use
render.yamlconfiguration (included) - Deploy
Health Check: https://your-app.onrender.com/health
MCP Endpoint: https://your-app.onrender.com/mcp
Heroku
# 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
- Connect GitHub repo
- Add environment variables
- Deploy with Procfile
Docker (Self-Hosted)
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"]
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 before deploying for commercial purposes.
🐛 Troubleshooting
Server Won't Start
Check Python version:
python --version # Should be 3.13+
Reinstall dependencies:
uv sync --reinstall
Rate Limiting Too Aggressive
Adjust in src/ytmcp/middleware/rate_limiter.py:
rate_limiter = RateLimiter(delay_seconds=0.5) # Faster (risky)
Render Deployment Fails
Check build logs:
- Ensure Python 3.13 is available
- Verify
runtime.txtspecifiespython-3.13
Common fix:
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:
- Review
/researchfor library capabilities - Follow existing tool patterns
- Maintain rate limiting
- Format outputs in Markdown
- Update documentation
Development Workflow:
# 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 file
🙏 Acknowledgments
Built with these excellent libraries:
- yt-dlp - Video metadata extraction
- scrapetube - Channel scraping
- youtube-search-python - Search
- youtube-transcript-api - Transcripts
- MCP Python SDK - Protocol foundation
📞 Support
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- Documentation: See
/researchfor design decisions
Built with ❤️ for the LLM ecosystem
