Music Collection MCP Server

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.

✨ Key Features

• 🎵 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

🚀 Quick Start

Option 1: Automated Setup (Recommended)

python scripts/setup.py

This guided setup will:

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

Option 2: Manual Installation

Using Python

# 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

Using Docker

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

🤖 MCP Client Setup

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

Python Installation

{
  "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"
      }
    }
  }
}

Docker Installation

{
  "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"
      ]
    }
  }
}

📁 Music Organization

The server supports multiple organization patterns:

Enhanced Structure (Recommended)

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)

Simple Structure (Also Supported)

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

🛠️ MCP Capabilities

Tools (10 total)

• 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

Resources (3 total)

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

Prompts (4 total)

• Information Gathering: fetch_band_info, analyze_band
• Analysis: `compare_ba

... View full README on GitHub