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
  • Local Development (STDIO)
  • Production Deployment (Render)
• Tool Categories
• Architecture
• Configuration
  • MCP Clients
  • Environment Variables
• API Reference
• Development
• Deployment Guide
• Security & Compliance
• Troubleshooting
• Contributing
• 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 (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:

1. Fork this repository

2. Create a new Web Service on Render:

   • Go to Render Dashboard
   • Click "New +" → "Web Service"
   • Connect your GitHub repository

3. 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
   

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)

{
  "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

📚 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:

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

# 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)

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.txt specifies python-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:

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:

# 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 /research for design decisions