youtube-mcp-server

KO | EN

gitlite — search

#ai-agent #python #dsh-plugin #mcp-server #agentic-ai #automation #genpark #llm-tools #deepseek-harness #ai-agents #dsh #claude-code

youtube-mcp-server

★ 56 Open GitHub ↗

A powerful Model Context Protocol (MCP) server for YouTube video transcription and metadata extraction.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

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

youtube-mcp-server

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README