music

This Music Collection MCP Server provides an AI-assisted interface for managing and analyzing a local music library. It offers intelligent music discovery with an 8-type album classification system (Album, EP, Live, Demo, Compilation, Single, Instrumental, Split), advanced analytics for collection health and recommendations, and flexible folder organization with safe migration tooling. The server exposes a set of MCP tools for discovering music, managing metadata, validating data integrity, performing complex searches, and generating insights. Use the scan_music_folders tool to detect and classify albums, get_band_list to filter and locate bands, and save_band_metadata/save_band_analyze to persist rich metadata and analyses. Advanced search and analytics endpoints enable multi-parameter filtering and comprehensive collection insights, while structure migration helps you reorganize folders without data loss.

Prerequisites:

• Python 3.8+
• Access to the local music directory you want to catalog
• Optional: Docker (for containerized deployment)

1. Clone the repository or download the MCP server package to a local directory.
2. Install Python dependencies:
   • python -m venv venv
   • source venv/bin/activate (Linux/macOS) or venv\Scripts\activate (Windows)
   • pip install -r requirements.txt
3. Prepare your environment:
   • Create or choose a music root path to catalog, e.g. /path/to/your/music
   • Create a configuration file if needed and note environment variables
4. Run the server:
   • Python: python main.py
   • Docker (optional): docker build -t music-mcp . docker run -v "/path/to/your/music:/music" -e MUSIC_ROOT_PATH=/music music-mcp
5. Verify startup in logs and connect MCP clients (e.g., Claude Desktop) using the generated configuration.

If you prefer automated setup, see the repository's automated setup script (scripts/setup.py) for guided installation and initial configuration.

Tips and common notes:

• Ensure MUSIC_ROOT_PATH points to your actual music directory and that the MCP server has read access.
• Adjust CACHE_DURATION_DAYS to balance freshness and performance according to your collection size.
• Set LOG_LEVEL to DEBUG during troubleshooting, then switch back to INFO or WARN for normal use.
• For Docker deployments, mount your music directory and pass environment variables to reflect your paths.
• If you migrate folder structures, use migrate_band_structure and back up data beforehand.
• The server is designed to work with Claude Desktop and other MCP clients; follow the Claude Desktop config examples in scripts/claude-desktop-configs/ to integrate.
• Regularly run health checks and validation scripts to keep metadata consistent (python scripts/health-check.py /path/to/music, python scripts/validate-music-structure.py /path/to/music).