# ia-programming/youtube-mcp architecture

> Architecture diagram of the GitHub repository ia-programming/youtube-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ia-programming/youtube-mcp
- Repository: https://github.com/ia-programming/youtube-mcp

## Overview

##### 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.”

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients
    subgraph "MCP Clients"
        MCPClient["MCP Client(s)"]:::client
    end

    %% MCP Server Container
    subgraph "MCP Server (server.py)"
        Dispatcher["Dispatcher"]:::internal
        SYHandler["search-youtube Handler"]:::internal
        GTHandler["get-transcript Handler"]:::internal
        SVHandler["store-video-info Handler"]:::internal
        STHandler["search-transcripts Handler"]:::internal
    end

    %% External Services
    subgraph "YouTube Service"
        YTSearch["Scraper/Search Module"]:::external
        YTTrans["Transcript Extraction Module"]:::external
    end
    GoogleAPI["Google Embeddings API"]:::external
    VectorDB["Vector Database"]:::db

    %% Configuration & Documentation
    subgraph "Configuration & Docs"
        PyProj["pyproject.toml"]:::config
        PythonVer[".python-version"]:::config
        UVLock["uv.lock"]:::config
        Gitignore[".gitignore"]:::config
        EnvFile[".env"]:::config
        Readme["README.md"]:::config
        License["LICENSE"]:::config
    end

    %% Client to Server calls
    MCPClient -->|"search-youtube"| SYHandler
    MCPClient -->|"get-transcript"| GTHandler
    MCPClient -->|"store-video-info"| SVHandler
    MCPClient -->|"search-transcripts"| STHandler

    %% Server internal flow
    SYHandler -->|"list videos"| YTSearch
    YTSearch -->|"video list"| SYHandler
    GTHandler -->|"fetch transcript"| YTTrans
    YTTrans -->|"transcript text"| GTHandler
    SVHandler -->|"fetch transcript & metadata"| YTTrans
    SVHandler -->|"embed video info"| GoogleAPI
    GoogleAPI -->|"embeddings"| SVHandler
    SVHandler -->|"store metadata & embeddings"| VectorDB
    STHandler -->|"semantic query"| VectorDB
    VectorDB -->|"ranked results"| STHandler

    %% Responses back to client
    SYHandler -->|"video list"| MCPClient
    GTHandler -->|"transcript text"| MCPClient
    SVHandler -->|"confirmation"| MCPClient
    STHandler -->|"search results"| MCPClient

    %% Configuration to Server
    PyProj --> Dispatcher
    PythonVer --> Dispatcher
    UVLock --> Dispatcher
    Gitignore --> Dispatcher
    EnvFile --> Dispatcher

    %% Click Events
    click Dispatcher "https://github.com/ia-programming/youtube-mcp/blob/main/server.py"
    click SYHandler "https://github.com/ia-programming/youtube-mcp/blob/main/server.py"
    click GTHandler "https://github.com/ia-programming/youtube-mcp/blob/main/server.py"
    click SVHandler "https://github.com/ia-programming/youtube-mcp/blob/main/server.py"
    click STHandler "https://github.com/ia-programming/youtube-mcp/blob/main/server.py"
    click PyProj "https://github.com/ia-programming/youtube-mcp/blob/main/pyproject.toml"
    click PythonVer "https://github.com/ia-programming/youtube-mcp/blob/main/.python-version"
    click UVLock "https://github.com/ia-programming/youtube-mcp/blob/main/uv.lock"
    click Gitignore "https://github.com/ia-programming/youtube-mcp/blob/main/.gitignore"
    click Readme "https://github.com/ia-programming/youtube-mcp/blob/main/README.md"
    click License "https://github.com/ia-programming/youtube-mcp/tree/main/LICENSE"

    %% Styles
    classDef internal fill:#cce5ff,stroke:#000,stroke-width:1px
    classDef external fill:#d4edda,stroke:#000,stroke-width:1px
    classDef db fill:#ffe5b4,stroke:#000,stroke-width:1px
    classDef config fill:#e2e3e5,stroke:#000,stroke-width:1px
    classDef client fill:#d6d8db,stroke:#000,stroke-width:1px
```
