home / mcp / music mcp server

Music MCP Server

Provides intelligent access to a local music collection with AI-powered metadata, analytics, and organization.

Installation

Add the following to your MCP client configuration file.

Configuration

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

You can turn your music collection into an intelligent, searchable library with AI-powered insights. This MCP server provides advanced metadata management, album type classification, and analytics to help you discover, organize, and understand your music like never before.

How to use

You interact with the Music Collection MCP Server through MCP clients. Start scanning your music folders to automatically classify albums into types like Album, EP, Live, Demo, Compilation, Single, Instrumental, and Split. Use the client to explore band collections, examine metadata, run analyses, and view insights like collection health and recommendations. You can migrate existing folder structures safely and take advantage of fast, batched operations and caching to keep your library responsive. If you use Claude Desktop or other MCP clients, you can connect to the server to perform discovery, metadata storage, validation, advanced searches, and analytics.

Practical usage patterns include: - Discover and classify your collection automatically as you add new music. - Inspect band metadata, analyze albums, and generate collection insights. - Filter and search albums with advanced criteria to find specific releases or patterns. - Migrate legacy folder structures with safety checks and rollback if needed. - Monitor collection health and maturity to guide curation decisions.

How to install

Choose your installation method and follow the steps to get the MCP server running and ready to serve MCP clients.

# Option 1: Automated Setup (Recommended)

python scripts/setup.py

Run the guided setup to verify system requirements, install dependencies, configure your music path, generate client configuration, and validate the 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

Or, run the server with Docker for containerized deployment.

# 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

Additional installation notes

Prerequisites you need to have installed include Python 3.8+ and Docker for containerized deployment. Ensure you have the required permissions to access your music directory and that your environment variables are correctly set for your chosen run method.

Configuration and runtime environment

Configure runtime behavior via environment variables or during the automated setup. The following variables are commonly used:

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)

Music organization patterns

The server supports flexible folder structures. The Enhanced Structure (recommended) organizes content by Band Name with subfolders for Album, Live, and Compilation, and an auto-generated metadata file at the band level. A Simple Structure is also supported, with releases organized directly under each Band folder.

Maintenance, scripts, and testing

Use the included maintenance scripts to keep your library healthy, back up data, and monitor the system. Regularly run health checks and validations to ensure your collection structure remains consistent.

Available tools

scan_music_folders

Smart scanning of music folders with 8-type album classification to detect Album, EP, Live, Demo, Compilation, Single, Instrumental, Split.

get_band_list

Advanced filtering and search for bands and collections.

save_band_metadata

Store detailed band metadata for quick retrieval.

save_band_analyze

Save analytical results about a band's collection.

save_collection_insight

Store insights about the entire music collection.

validate_band_metadata

Perform a dry-run validation of metadata integrity.

advanced_search_albums

Perform complex searches with multiple parameters.

analyze_collection_insights

Generate comprehensive collection analytics.

migrate_band_structure

Migrate folder structures with safety checks and rollback.

fetch_band_info

Retrieve detailed information about a band.