# 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**:
```bash
git clone https://github.com/mourad-ghafiri/youtube-mcp-server
cd youtube-mcp-server
```
2. **Install dependencies**:
Using `uv` (recommended):
```bash
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
```bash
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:
```json
{
"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.
```json
{
"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.
```json
{
"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.
---
<p align="center">Built with love ❤️</p>
