YouTube MCP Server

A powerful Model Context Protocol (MCP) server for YouTube video transcription and metadata extraction. This server provides advanced tools for AI agents to retrieve video metadata and generate high-quality transcriptions with native language support.

🌟 Features

• Metadata Extraction: Retrieve comprehensive video details (title, description, views, duration, etc.) without downloading the video.
• Smart Transcription:
  • In-Memory Processing: fast, efficient, and disk-I/O free pipeline.
  • VAD (Voice Activity Detection): uses Silero VAD for precise segmentation.
  • Multilingual Support: supports 99 languages.
  • Translation: Transcribe to any supported language.
• Caching: Intelligent file-based caching to avoid redundant processing.
• Optimized Performance:
  • Uses yt-dlp for robust extraction.
  • Hardware acceleration (MPS/CUDA) for Whisper inference.
  • Parallel processing for transcription segments.

🛠️ Prerequisites

• Python 3.10+
• ffmpeg: Required for audio processing.
  • Mac: brew install ffmpeg
  • Linux: sudo apt install ffmpeg
  • Windows: Download and add to PATH.

📦 Installation

1. Clone the repository:

   git clone https://github.com/mourad-ghafiri/youtube-mcp-server
   cd youtube-mcp-server
   

2. Install dependencies: Using uv (recommended):

   uv sync
   

⚙️ Configuration

The server configuration is located in src/youtube_mcp_server/config.py. You can adjust the following parameters:

Directories

• TRANSCRIPTIONS_DIR: Directory where transcription JSON files are cached (default: "transcriptions").

Models

• WHISPER_MODEL_NAME: OpenAI Whisper model to use. Options: "tiny", "base", "small", "medium", "large", "turbo". (default: "tiny").

  Note: Larger models require more RAM and a GPU (CUDA/MPS).

• SILERO_REPO / SILERO_MODEL: VAD model repository and ID.

Audio Processing

• SAMPLING_RATE: Audio sampling rate for Whisper/VAD (default: 16000 Hz).
• SEGMENT_PADDING_MS: Padding added to each audio segment to avoid cutting off words (default: 200 ms).

Concurrency

• MAX_WORKERS: Number of parallel threads for transcribing audio segments (default: 4). Increasing this speeds up transcription but uses more CPU/Memory.

🚀 Usage

1. Start the Server

uv run main.py

The server runs on SSE (Server-Sent Events) transport at http://127.0.0.1:8000/sse.

2. Configure MCP Client

Add the server configuration to your MCP client:

{
  "mcpServers": {
    "youtube": {
      "url": "http://127.0.0.1:8000/sse"
    }
  }
}

🛠️ Tools Reference

get_video_info

Retrieves metadata for a given YouTube video.

• Input: url (string)
• Output: JSON object with title, views, description, thumbnails, etc.

  {
    "id": "VIDEO_ID",
    "title": "Video Title",
    "description": "Video description...",
    "view_count": 1000000,
    "duration": 212,
    "uploader": "Channel Name",
    "upload_date": "20091025",
    "thumbnail": "https://i.ytimg.com/...",
    "tags": ["tag1", "tag2"],
    "categories": ["Music"]
  }
  

transcribe_video

Transcribes a video with optional translation.

• Inputs:
  • url (string): Video URL.
  • language (string, default="auto"):
    • "auto": Transcribe in detected language.
    • "en": Translate to English.
    • "fr", "es", etc.: Transcribe in specific language.
• Output: JSON with segments and metadata.

  {
    "id": "VIDEO_ID",
    "title": "Video Title",
    "duration": 212,
    "transcription": [
      {
        "from": "00:00:00",
        "to": "00:00:05",
        "transcription": "First segment text..."
      },
      {
        "from": "00:00:05",
        "to": "00:00:10",
        "transcription": "Second segment text..."
      }
    ]
  }
  

🏗️ Technical Architecture

• Services: DownloadService, VADService (Silero), WhisperService (OpenAI), CacheService.
• In-Memory Pipeline: Audio is downloaded -> loaded to RAM -> segmented by VAD -> transcribed by Whisper -> Cached.
• Concurrency: Parallel segment transcription.

🌍 Appendix: Supported Languages

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the project
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📄 License

Distributed under the MIT License. See LICENSE for more information.

Built with love ❤️