playlist

This MCP server is a Python-based tool powered by uv (async web server) that listens for requests to generate mood- or theme-based music playlists. It scans your local music library, reads metadata with Mutagen, filters tracks to match a requested vibe, and outputs a .m3u playlist saved to a user-specified directory. You can invoke it from an LLM like Claude to generate playlists such as “chill evening” or “workout mix,” and then import the resulting .m3u into your preferred music player. The workflow relies on local file access and metadata extraction, so ensure your music library is accessible to the server process and that you have permission to read files and write the output playlist. Tools exposed by this server include: (1) local file scanning and metadata extraction via Mutagen, (2) mood/theme-based filtering logic to select tracks, and (3) creation and saving of .m3u playlists to a chosen path on the host machine.

Prerequisites:

• Python 3.8+ installed on your system
• Access to install Python packages from the internet

Install the required Python packages:

pip install uv mutagen

Clone the repository and start the server:

git clone https://github.com/slug/m4dd0c-playlist-mcp-server.git
cd m4dd0c-playlist-mcp-server

uvicorn mcp_server:app --reload

Usage notes:

• The server runs an asynchronous web app via uvicorn. Ensure port accessibility if you plan to expose it to other tools.
• The README describes how to prompt Claude (or other LLMs) to request mood-based playlists; this server handles the generation and storage of the .m3u file.

Tips and caveats:

• Ensure your music directory is readable by the process running uvicorn and that the output directory exists or is creatable by the process.
• Supported formats depend on Mutagen capabilities and the underlying file types in your library (Mutagen supports common formats like MP3, FLAC, AAC, etc.). If a file’s metadata cannot be read, it may be skipped.
• After generating a playlist, you may need to re-index your music library or refresh your media player’s library to reflect the new .m3u file location.
• If you plan to expose the MCP server beyond localhost, implement appropriate authentication and secure your endpoints.
• API route structure and example requests can be added to the README if you plan to share dev integration details.