How ia-programming/youtube-mcp works
Project Type and Purpose
• This is a backend “MCP server” microservice written in Python.
• It exposes four main “tools” (endpoints) to MCP-compatible clients (e.g., Claude Desktop):
• search-youtube
• get-transcript
• store-video-info
• search-transcripts
• It integrates with external systems: YouTube (scraping/transcripts), Google Embeddings API, and a vector database.
File Structure
• Top-level files only; everything lives in server.py.
• Configuration in pyproject.toml, uv.lock, .env (GOOGLE_API_KEY).
• No frontend or other services—this is a single microservice.
Extract Key Components from README
• Server entrypoint: server.py
• External dependencies:
• YouTube scraping/transcript provider (no official API)
• Google Embeddings API (requires GOOGLE_API_KEY)
• Vector database (stores video info + transcript embeddings)
• MCP clients (Claude.app or any other client)
• Tools mapping to handlers inside server.py.
Main Components
A. MCP Server (server.py)
• Listener / Dispatcher for incoming MCP requests
• Tool-specific handlers:
1. search-youtube Handler
2. get-transcript Handler
3. store-video-info Handler
4. search-transcripts Handler
B. YouTube Service
• Scraper / Search Module
• Transcript Extraction Module
C. Google Embeddings Service
• External HTTP API call (uses GOOGLE_API_KEY)
D. Vector Database
• Stores metadata + embeddings
• Provides semantic search queries
E. MCP Client(s)
• Claude Desktop or any MCP-compatible client
F. Configuration & Environment
• .env for secrets
• uv package manager and Python runtime
Relationships & Data Flows
• MCP Client → MCP Server: “search-youtube” call
→ Server calls YouTube Service → returns video list → Server returns to client.
• MCP Client → MCP Server: “get-transcript” call
→ Server calls YouTube Service → transcript text → Server returns.
• MCP Client → MCP Server: “store-video-info” call
→ Server fetches transcript & video metadata
→ Server calls Google Embeddings → receives vector embeddings
→ Server stores (metadata + embeddings) in Vector DB → returns confirmation.
• MCP Client → MCP Server: “search-transcripts” call
→ Server forwards query to Vector DB → receives ranked results → returns to client.
Architectural Patterns & Design Principles
• Single-responsibility for each handler/module.
• Clear separation between:
• Protocol layer (MCP server entrypoint & dispatcher)
• Integration layer (YouTube scraping, Google API)
• Persistence layer (vector database)
• Externalize configuration (GOOGLE_API_KEY in .env).
Putting It All Together
• Right side: External “YouTube Service” & “Google Embeddings API.”
• Bottom: “Vector Database.”