scan_music_foldersLABSCO SUMMARY
Writes what it learns back next to the music.
Most collection tools only read. Here the metadata, per-band analysis and collection insights are saved, with a dry-run validation step first, so the knowledge accumulates instead of being regenerated every session. The advanced album search with its wide filter set is the tool you will actually use daily; the migration tool exists for the day you decide to reorganise the folders.
What it is
An MCP server for a music collection on your own disk. It scans the folder structure, detects how it is organised, and then acts as a place to store what you or the assistant learn about each band — metadata, analysis, collection-wide observations — with validation before anything is written. It supports both an enhanced folder layout and a simple one.
What you get
- The music folder scanned with structure type detected, and the resulting band list filtered and searched —
scan_music_folders,get_band_list - Band metadata, per-band analysis and collection-level observations saved back —
save_band_metadata,save_band_analyze,save_collection_insight - Metadata validated as a dry run before it is committed —
validate_band_metadata - Album search across a 13-parameter filter set, which is the difference between browsing and actually finding something —
advanced_search_albums - Collection-wide analysis rather than per-record facts —
analyze_collection_insights - A safe migration between folder structures for when you reorganise —
migrate_band_structure - Three resources to read from:
band://info/{band_name},collection://summary,collection://analytics - Four prompts for the recurring jobs:
fetch_band_info,analyze_band,compare_bands,collection_insights
Requirements
Python 3.8+, or Docker. MUSIC_ROOT_PATH is the one required setting — the directory holding your collection; under Docker it is mounted in and the variable points at the mount. CACHE_DURATION_DAYS defaults to 30 and LOG_LEVEL to INFO. python scripts/setup.py runs a guided setup that checks requirements, installs dependencies, sets the music path, writes the Claude Desktop configuration and validates the result — the fastest way in.
Setup effort
Build from source — clone the repository, then follow the project's own run instructions
USE CASES
01
Getting a collection into a state you can query
Scan the folder, let it detect the structure, then read the band list back with filters instead of browsing directories.
02
Finding an album by what you remember about it
Use the advanced album search with several filters at once rather than a single name match.
03
Building up notes on a band
Validate the metadata as a dry run first, then save it and the analysis so it is there next session.
04
Seeing the shape of the whole collection
Run the collection-wide analysis and save the observation, rather than reasoning band by band.
05
Reorganising folders without losing anything
Use the structure migration instead of moving directories by hand and re-scanning from scratch.
9 tools
Listed in project docs. Your client may show a different list.
get_band_listsave_band_metadatasave_band_analyzesave_collection_insightvalidate_band_metadataadvanced_search_albumsanalyze_collection_insightsmigrate_band_structureBEFORE YOU INSTALL
What to know first
Tools you get
9 tools named in the project's documentation.
Requires
Python 3.8+
Where it runs
The documented client runs the server on your machine.
INSTALLATION
Connect your client
Server setup
TERMINAL
python scripts/setup.pyMCP Clients
Claude Desktop
CLAUDE DESKTOP · JSON
{
"mcpServers": {
"music-collection": {
"command": "python",
"args": [
"<YOUR_PATH_TO_MUSIC_MCP_SERVER>/main.py"
],
"env": {
"MUSIC_ROOT_PATH": "<YOUR_MUSIC_ROOT_PATH>"
}
}
}
}
