Music Collection MCP Server

An MCP server for intelligent access to your local music collection, featuring metadata management, band discovery, and advanced querying.

A powerful Model Context Protocol (MCP) server that provides intelligent access to your local music collection through advanced metadata management, album type classification, and comprehensive analytics.

- 🎵 Smart Music Discovery: Intelligent scanning with 8-type album classification (Album, EP, Live, Demo, Compilation, Single, Instrumental, Split)
- 📊 Advanced Analytics: Collection maturity assessment, health scoring, and personalized recommendations
- 🏗️ Flexible Organization: Support for multiple folder structures with automated migration and compliance scoring
- ⚡ High Performance: Optimized scanning (20-30% faster), batch operations, and intelligent caching
- 🤖 AI Integration: Works seamlessly with Claude Desktop and other MCP clients
- 🔄 Automated Setup: One-command installation with configuration generation

- Check system requirements
- Install dependencies
- Configure your music collection path
- Generate Claude Desktop configuration
- Validate your setup

# Install dependencies pip install -r requirements.txt # Set your music path export MUSIC_ROOT_PATH="/path/to/your/music" # Run the server python main.py

# Build and run docker build -t music-mcp . docker run -v "/path/to/your/music:/music" -e MUSIC_ROOT_PATH=/music music-mcp

Configuration File Locations for Claude desktop

- Windows:%APPDATA%\Claude\claude_desktop_config.json
- macOS:~/Library/Application Support/Claude/claude_desktop_config.json
- Linux:~/.config/Claude/claude_desktop_config.json

{ "mcpServers": { "music-collection": { "command": "python", "args": ["/path/to/music-mcp-server/main.py"], "env": { "MUSIC_ROOT_PATH": "/path/to/your/music", "CACHE_DURATION_DAYS": "30", "LOG_LEVEL": "INFO" } } } }

{ "mcpServers": { "music-collection": { "command": "docker", "args": [ "run", "--rm", "--interactive", "-v", "/path/to/your/music:/music", "-e", "MUSIC_ROOT_PATH=/music", "-e", "CACHE_DURATION_DAYS=30", "music-mcp" ] } } }

The server supports multiple organization patterns:

Band Name/ ├── Album/ │ ├── 1973 - Dark Side of the Moon/ │ └── 1979 - The Wall (Deluxe)/ ├── Live/ │ └── 1988 - Delicate Sound of Thunder/ ├── Compilation/ │ └── 2001 - Echoes - Best Of/ └── .band_metadata.json (auto-generated)

Band Name/ ├── 1973 - Dark Side of the Moon/ ├── 1988 - Delicate Sound of Thunder (Live)/ └── 2001 - Echoes - Best Of (Compilation)/

- Music Discovery:scan_music_folders- Smart scanning with type detection
- Collection Management:get_band_list- Advanced filtering and search
- Metadata Storage:save_band_metadata,save_band_analyze,save_collection_insight
- Validation:validate_band_metadata- Dry-run validation
- Advanced Search:advanced_search_albums- 13-parameter filtering system
- Analytics:analyze_collection_insights- Comprehensive collection analysis
- Structure Migration:migrate_band_structure- Safe folder organization migration

- Band Info:band://info/{band_name}- Detailed band information
- Collection Summary:collection://summary- Overview and statistics
- Advanced Analytics:collection://analytics- Deep collection analysis

- Information Gathering:fetch_band_info,analyze_band
- Analysis:compare_bands,collection_insights

Configure via environment variables or the automated setup:

MUSIC_ROOT_PATH="/path/to/your/music" # Required: Your music directory CACHE_DURATION_DAYS=30 # Optional: Cache expiration (default: 30) LOG_LEVEL=INFO # Optional: Logging level (default: INFO)

- Quick Start Guide- Get running in minutes
- Installation Guide- Detailed setup instructions
- Configuration Guide- Advanced configuration options

- Usage Examples- Real-world examples
- Collection Organization- Best practices
- Album Handling- Understanding album types

- FAQ- Common questions
- Troubleshooting- Problem solving
- Rating System- Understanding ratings and analysis

# Using Docker (recommended) docker build -f Dockerfile.test -t music-mcp-tests . docker run --rm music-mcp-tests python -m pytest . -v # Using Python python -m pytest tests/ -v

- Migration Tools: Safe folder structure migration with backup and rollback
- Advanced Analytics: Collection maturity assessment and health scoring
- Performance: 20-30% faster scanning with optimized file operations
- Separated Schema: Local vs missing albums for better management
- Automated Setup: One-command installation and configuration
- Album Types: Intelligent 8-type classification system
- Flexible Structure: Support for multiple organization patterns
- Check theFAQfor common questions
- Run health check:python scripts/health-check.py /path/to/music
- Validate structure:python scripts/validate-music-structure.py /path/to/music
- ReviewTroubleshootingguide

Deterministic music-theory engine for AI agents to analyze, resolve, voice, and reharm chords.