Skip to main content
Glama
Utkarshchaudhary009

YtMCP

by Utkarshchaudhary009
OverviewSchemaRelated ServersScoreDiscussions
Python
Hybrid

YtMCP - YouTube Model Context Protocol Server

Python 3.13+ MCP License: MIT Deploy to Render

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

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

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:

Deploy to Render

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

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:

  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:

📞 Support

Built with ❤️ for the LLM ecosystem

Star on GitHub

This server cannot be installed

-
security - not tested
F
license - not found
-
quality - not tested

How are these scores calculated?

Resources

New MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Utkarshchaudhary009/YtMCP'

If you have feedback or need assistance with the MCP directory API, please join our Discord server