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

Country (Primary/Region)	Language	Code
South Africa	Afrikaans	af
Ethiopia	Amharic	am
Arab World	Arabic	ar
India	Assamese	as
Azerbaijan	Azerbaijani	az
Russia	Bashkir	ba
Belarus	Belarusian	be
Bulgaria	Bulgarian	bg
Bangladesh	Bengali	bn
Tibet	Tibetan	bo
France (Brittany)	Breton	br
Bosnia and Herzegovina	Bosnian	bs
Spain (Catalonia)	Catalan	ca
Czech Republic	Czech	cs
Wales	Welsh	cy
Denmark	Danish	da
Germany	German	de
Greece	Greek	el
USA / UK	English	en
Spain	Spanish	es
Estonia	Estonian	et
Spain (Basque)	Basque	eu
Iran	Persian	fa
Finland	Finnish	fi
Faroe Islands	Faroese	fo
France	French	fr
Spain (Galicia)	Galician	gl
India	Gujarati	gu
Nigeria	Hausa	ha
Hawaii	Hawaiian	haw
Israel	Hebrew	he
India	Hindi	hi
Croatia	Croatian	hr
Haiti	Haitian Creole	ht
Hungary	Hungarian	hu
Armenia	Armenian	hy
Indonesia	Indonesian	id
Iceland	Icelandic	is
Italy	Italian	it
Japan	Japanese	ja
Indonesia (Java)	Javanese	jw
Georgia	Georgian	ka
Kazakhstan	Kazakh	kk
Cambodia	Khmer	km
India	Kannada	kn
South Korea	Korean	ko
Ancient Rome	Latin	la
Luxembourg	Luxembourgish	lb
Congo	Lingala	ln
Laos	Lao	lo
Lithuania	Lithuanian	lt
Latvia	Latvian	lv
Madagascar	Malagasy	mg
New Zealand	Maori	mi
North Macedonia	Macedonian	mk
India	Malayalam	ml
Mongolia	Mongolian	mn
India	Marathi	mr
Malaysia	Malay	ms
Malta	Maltese	mt
Myanmar	Myanmar	my
Nepal	Nepali	ne
Netherlands	Dutch	nl
Norway	Nynorsk	nn
Norway	Norwegian	no
France (Occitania)	Occitan	oc
India (Punjab)	Punjabi	pa
Poland	Polish	pl
Afghanistan	Pashto	ps
Portugal / Brazil	Portuguese	pt
Romania	Romanian	ro
Russia	Russian	ru
India	Sanskrit	sa
Pakistan	Sindhi	sd
Sri Lanka	Sinhala	si
Slovakia	Slovak	sk
Slovenia	Slovenian	sl
Zimbabwe	Shona	sn
Somalia	Somali	so
Albania	Albanian	sq
Serbia	Serbian	sr
Indonesia	Sundanese	su
Sweden	Swedish	sv
East Africa	Swahili	sw
India	Tamil	ta
India	Telugu	te
Tajikistan	Tajik	tg
Thailand	Thai	th
Turkmenistan	Turkmen	tk
Philippines	Tagalog	tl
Turkey	Turkish	tr
Russia (Tatarstan)	Tatar	tt
Ukraine	Ukrainian	uk
Pakistan	Urdu	ur
Uzbekistan	Uzbek	uz
Vietnam	Vietnamese	vi
Ashkenazi Jewish	Yiddish	yi
Nigeria	Yoruba	yo
China (Guangdong)	Cantonese	yue
China	Chinese	zh

🤝 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 ❤️