musicolet-mcp

Local tools for extracting listening metrics from Musicolet backup files, building a static dashboard, and exposing the same workflow through an optional MCP server.

This project is designed for power users who want their own music listening analytics without sending their library or listening history to a hosted service.

Features

• Decode Musicolet backup ZIP files that contain encrypted app data.
• Extract song, play-count, recent listening, artist, album, month, week, and year metrics.
• Generate CSV files plus summary.json.
• Build a static, local HTML dashboard.
• Run as a CLI or optional MCP server for agent workflows.

Quick Start

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e ".[dev,mcp]"

musicolet-mcp extract C:\path\to\musicolet_backup.zip --out-dir outputs\latest
musicolet-mcp dashboard outputs\latest --out outputs\latest\dashboard.html

Open outputs\latest\dashboard.html in a browser.

For a recurring Syncthing or USB drop folder:

musicolet-mcp update-latest data\incoming --out-dir outputs\latest

MCP Server

musicolet-mcp-server

Tools exposed by the server:

• extract_musicolet_metrics
• build_musicolet_dashboard
• read_musicolet_summary
• update_from_latest_musicolet_backup

Background

The extraction logic is based on local inspection of Musicolet backups. Backup internals are not an official public API and may change. The project aims to fail gracefully if a future Musicolet version changes its schema.