YO
Media

YouTube Video Information Extractor MCP Server with Proxies

Extract YouTube video info with proxies using an MCP server for fast, reliable metadata retrieval and IP-managed requests.

View on GitHub

Overview

This MCP (Model Context Protocol) server extracts YouTube video metadata while routing requests through configurable proxy pools. It’s intended for developers who need fast, reliable access to YouTube video information (title, description, thumbnails, duration, uploader, tags, etc.) without exposing a single source IP that might be rate-limited or blocked by YouTube. By combining a small HTTP extraction service with proxy management and optional caching, the server helps applications scale metadata collection and maintain uptime under IP-based throttling.

The server is implemented as a lightweight MCP-compatible service that accepts video URLs or IDs and returns normalized JSON metadata. It’s useful for analytics pipelines, content moderation systems, archiving tools, search/indexing crawlers, and any downstream system that requires consistent YouTube metadata without embedding scraping logic or proxy rotation in multiple places.

Features

  • Extracts standard YouTube metadata: title, description, thumbnails, duration, view counts, upload date, author, tags, available formats.
  • Configurable proxy pool with rotation strategies (round-robin, random).
  • HTTP API compatible with MCP-style inference services for easy integration.
  • Optional request-level timeouts and retry logic to handle transient failures.
  • Caching layer to reduce repeated requests for the same video and lower proxy usage.
  • Health and status endpoints for monitoring proxy health and server availability.
  • Example client and CLI snippets for quick local testing.

Installation / Configuration

Clone the repository and install dependencies (Python example):

git clone https://github.com/Klavis-AI/klavis.git
cd klavis/mcp_servers/youtube
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Environment configuration (example .env):

# .env
MCP_HOST=0.0.0.0
MCP_PORT=8080
PROXIES_FILE=./config/proxies.txt
PROXY_ROTATION=round_robin    # or "random"
REQUEST_TIMEOUT=15            # seconds
CACHE_ENABLED=true
CACHE_TTL=3600                # seconds
LOG_LEVEL=info

Example proxies file (proxies.txt). Each proxy on its own line; support for HTTP(S) proxies with auth:

http://username:[email protected]:3128
http://12.34.56.79:8080
socks5://user:[email protected]:1080

Start the server (example with uvicorn):

uvicorn app:app --host $MCP_HOST --port $MCP_PORT --reload

Or run with Docker (example Dockerfile provided in repo):

docker build -t youtube-mcp .
docker run -p 8080:8080 \
  -e PROXIES_FILE=/app/config/proxies.txt \
  -e PROXY_ROTATION=round_robin \
  youtube-mcp

Available Tools / Resources

  • HTTP API endpoint (MCP-style): POST /v1/extract — submit JSON payload containing a YouTube URL or ID and receive normalized metadata.
  • Health endpoint: GET /health — basic liveness and readiness checks.
  • Proxy manager: monitors proxy pool, performs basic validation and rotation.
  • Example client: examples/client.py — demonstrates how to call the extraction endpoint and handle responses.
  • Config templates: config/proxies.txt, config/example.env — starting points for production configuration.

API Example and Response Schema

Example request:

curl -X POST "http://localhost:8080/v1/extract" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"}'

Typical JSON response fields:

FieldTypeDescription
idstringYouTube video ID
titlestringVideo title
descriptionstringFull description text
thumbnailsarrayList of thumbnail URLs + sizes
durationnumberDuration in seconds
viewCountnumberView count (if available)
likeCountnumberLikes (if available)
authorobjectChannel name and ID
uploadDatestringISO date of upload
tagsarrayList of tags
formatsarrayAvailable streaming formats / mime types
extractedAtstringISO timestamp when extraction happened
sourceProxystringProxy used for the request (for debugging)

Use Cases

  • Scalable metadata ingestion: periodically extract metadata for large playlists or channel inventories while distributing requests across many proxies to avoid IP throttles.
  • Content moderation pipelines: fetch descriptions, titles, tags and thumbnails for automated classifiers without embedding proxy logic in your moderation worker.
  • Search and discovery: power a video indexer that needs up-to-date metadata and more reliable availability under rate limits.
  • Archival and backup: gather consistent metadata snapshots for long-term storage, with caching to avoid repeated fetches of identical items.
  • Regional testing: route requests through geo-located proxies to verify region-specific availability or metadata differences.

Best Practices & Troubleshooting

  • Use HTTPS-capable proxies and ensure they support the required protocols (HTTP, HTTPS, or SOCKS5).
  • Start with a modest proxy pool and increase size if you see rate limits or blocking; monitor /health and logs to detect failing proxies.
  • Enable caching for frequently requested videos to reduce load and proxy usage.
  • Tune REQUEST_TIMEOUT and retry logic to balance responsiveness and resilience against slow proxies.
  • If extraction failures persist, rotate to fresh proxies and check whether YouTube responses require additional headers or
Tags:media