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