mcp-bgm-recommender

# Find BGM MCP Server An MCP server that helps YouTube content creators find perfect background music for their shorts by analyzing script content and recommending tracks from YouTube Music. ## Features - **Script Analysis**: Analyzes mood, theme, pacing, and sentiment from video scripts - **Smart Recommendations**: Uses YouTube Music API to find suitable background tracks - **Duration Filtering**: Ensures recommendations fit your short video length - **Confidence Scoring**: Ranks recommendations by relevance to your content ## Architecture The server follows clean architecture principles with modular design: ```text find_bgm/ ├── server.py # Main server entry point ├── config.py # Configuration management ├── models.py # Data models and types ├── script_analyzer.py # Script analysis logic ├── music_service.py # YouTube Music API integration ├── tools.py # MCP tool definitions └── test_server.py # Test suite ``` ## Installation 1. Install dependencies: ```bash pip install -r requirements.txt ``` 2. (Optional) Set up YouTube Music API access: - Follow the [ytmusicapi setup guide](https://ytmusicapi.readthedocs.io/en/stable/setup.html) - Create `oauth.json` file in the project directory - Without this, the server will use mock recommendations ## Usage The server provides one main tool: `recommend_background_music` ### Parameters - `script` (required): Your YouTube short script/content - `duration` (required): Length of your short in seconds (15-60) - `genre_preference` (optional): "pop", "electronic", "chill", "rock", "hip-hop", "classical", "ambient", "any" - `mood_preference` (optional): "upbeat", "calm", "dramatic", "energetic", "relaxed", "motivational", "any" - `content_type` (optional): "comedy", "educational", "lifestyle", "fitness", "cooking", "travel", "tech", "other" ### Example Response ```json { "analysis": { "detected_mood": "motivational", "detected_theme": "fitness", "pacing": "medium", "sentiment_score": 0.4, "keywords": ["workout", "energy", "strong"] }, "recommendations": [ { "title": "Uplifting Corporate Background", "artist": "Audio Library", "youtube_music_id": "abc123", "confidence_score": 0.85, "reason": "Strong match for motivational mood and fitness content", "duration": 45, "loop_suitable": true } ] } ``` ## Configuration Customize behavior with environment variables: ```bash # Logging level export BGM_LOG_LEVEL=DEBUG # OAuth file location export BGM_OAUTH_FILE=my_oauth.json # Search and recommendation limits export BGM_MAX_DURATION=240 export BGM_SEARCH_LIMIT=15 ``` ## YouTube Music API Setup ### Method 1: Browser Authentication (Recommended) 1. Install ytmusicapi: `pip install ytmusicapi` 2. Run: `ytmusicapi browser` 3. Follow prompts to paste browser headers from YouTube Music 4. Save as `oauth.json` ### Method 2: OAuth Setup 1. Create Google Cloud project 2. Enable YouTube Data API v3 3. Create OAuth credentials 4. Run: `ytmusicapi oauth` 5. Complete authentication flow Without the API, the server works with mock data for testing. ## Running the Server ```bash python server.py ``` The server runs on stdio and can be integrated with any MCP-compatible client. ## Testing ```bash # Test all components python test_server.py # Test with virtual environment source venv/bin/activate python test_server.py ``` ## Claude Desktop Integration Add to your `claude_desktop_config.json`: ```json { "mcpServers": { "find-bgm": { "command": "/path/to/find_bgm/venv/bin/python", "args": ["/path/to/find_bgm/server.py"] } } } ``` ## Components ### ScriptAnalyzer Analyzes script content to detect mood, theme, and pacing using natural language processing. ### YouTubeMusicService & MusicRecommendationService Handles YouTube Music API integration and generates scored recommendations. ### BGMTools MCP tool interface that orchestrates script analysis and music recommendations. ### Configuration Management Environment-based configuration with sensible defaults and type safety. ## Example Usage ```python from models import RecommendationRequest from script_analyzer import ScriptAnalyzer from music_service import MusicRecommendationService # Analyze script analyzer = ScriptAnalyzer() analysis = analyzer.analyze_script("Your video script here") # Get recommendations service = MusicRecommendationService(music_service, config) recommendations = await service.get_recommendations( analysis, "electronic", "upbeat", 30 ) ``` The server provides intelligent music recommendations to help creators find the perfect soundtrack for their content! 🎵