YouTube Music MCP Server

AI destekli doğal dil ile müzik keşfi yapan MCP (Model Context Protocol) server’ı.

🎵 Özellikler

• Doğal Dil İşleme: “Üzgün hissediyorum, sakin müzikler öner” gibi doğal istekleri anlayabilir
• Duygu Durumu Bazlı Arama: Mutlu, üzgün, sakin, enerjik vs. ruh haline göre müzik önerileri
• Aktivite Bazlı Arama: Egzersiz, ders çalışma, araba kullanma vs. aktivitelere uygun müzikler
• Sanatçı Araması: Belirli sanatçıların şarkılarını bulma
• Trend Müzikler: Bölgesel popüler müzikleri getirme
• Canlı Yayınlar: Aktif müzik yayınlarını bulma

📋 Mevcut MCP Tools

1. search_music(query) - Genel müzik araması
2. search_by_mood(mood) - Duygu durumuna göre arama
3. search_by_activity(activity) - Aktivite bazlı arama
4. get_trending_music(region) - Popüler müzikler
5. get_live_music_streams() - Canlı yayınlar
6. search_artist_songs(artist) - Sanatçı şarkıları

🛠️ Kurulum

1. Gereksinimler

pip install -r requirements.txt

2. YouTube API Key

Google Cloud Console’dan YouTube Data API v3 key alın:

1. Google Cloud Console > APIs & Services > Credentials
2. “Create Credentials” > “API Key”
3. API key’i kopyalayın

3. Environment Variables

export YOUTUBE_API_KEY="YOUR_YOUTUBE_API_KEY"
export DEFAULT_REGION="TR"  # Opsiyonel

4. Server’ı Çalıştırma

python server.py

🧪 Test Etme

Server çalıştıktan sonra test için:

# Test komutu
echo '{"method": "tools/call", "params": {"name": "search_music", "arguments": {"query": "pop music"}}}' | python server.py

🎯 Kullanım Örnekleri

Doğal Dil Örnekleri:

• “Stresli bir günden sonra rahatlatıcı müzikler”
• “Egzersiz yaparken dinlenecek enerjik şarkılar”
• “Romantik akşam yemeği için müzik”
• “Ders çalışırken odaklanmaya yardımcı müzikler”

Tool Çağrıları:

{
  "method": "tools/call",
  "params": {
    "name": "search_by_mood",
    "arguments": {
      "mood": "sakin"
    }
  }
}

📊 API Quota Yönetimi

• YouTube Data API v3: Günlük 10,000 unit
• Search işlemi: ~100 unit
• Yaklaşık günlük ~100 arama yapılabilir

🔧 Konfigürasyon

Desteklenen Mood’lar:

• Türkçe: mutlu, üzgün, sakin, enerjik, romantik, nostaljik, kızgın, odaklanma
• İngilizce: happy, sad, calm, energetic, romantic, nostalgic, angry, focused

Desteklenen Aktiviteler:

• Türkçe: egzersiz, ders, yemek, araba, parti, uyku, iş, meditasyon
• İngilizce: workout, study, cooking, driving, party, sleep, work, meditation

Desteklenen Bölgeler:

• TR (Türkiye), US (Amerika), GB (İngiltere), DE (Almanya), FR (Fransa), IT (İtalya), ES (İspanya)

🐳 Docker ile Çalıştırma

# Docker image oluştur
docker build -t youtube-music-mcp .

# Container çalıştır
docker run -e YOUTUBE_API_KEY="YOUR_YOUTUBE_API_KEY" youtube-music-mcp

📝 Smithery.yaml

MCP server’ı Smithery ile kullanmak için:

youtube_api_key: "YOUR_YOUTUBE_API_KEY"
region: "TR"

🚨 Hata Yönetimi

Server aşağıdaki durumları handle eder:

• API key eksik/geçersiz
• Quota aşımı
• Network hataları
• Geçersiz arama parametreleri
• Sonuç bulunamama

🔍 Log Seviyeleri

# Debug mod için
logging.basicConfig(level=logging.DEBUG)

📞 API Response Format

{
  "status": "success",
  "message": "10 müzik bulundu",
  "query": "pop music",
  "results": [
    {
      "video_id": "abc123",
      "title": "Pop Song Title",
      "channel": "Artist Name",
      "thumbnail": "https://img.youtube.com/...",
      "published_at": "2024-01-01T00:00:00Z",
      "youtube_url": "https://www.youtube.com/watch?v=abc123"
    }
  ]
}

📱 Mobil Uygulama Entegrasyonu

Bu MCP server, AI destekli müzik keşif mobil uygulaması için tasarlanmıştır. VoltAgent ile entegre edilerek doğal dil işleme yetenekleri sağlar.

🤝 Katkı

1. Fork edin
2. Feature branch oluşturun
3. Commit edin
4. Push edin
5. Pull Request oluşturun

📄 Lisans

MIT License

🎵 Geliştirici Notları

• API responses UTF-8 encoding kullanır
• Async/await pattern ile yazılmıştır
• Comprehensive error handling mevcuttur
• Music-focused filtering algoritması vardır
• Quota management sistemi entegredir

🔐 Güvenlik Uyarıları

• ÖNEMLİ: Gerçek API key’lerinizi asla kodunuzda saklamayın!
• Environment variables veya güvenli konfigürasyon dosyaları kullanın
• .env dosyalarınızı .gitignore’a ekleyin
• Public repository’lerde API key paylaşmayın

Not: YouTube API key’inizi güvenli tutun ve public repository’lerde paylaşmayın!