urmusic-mcp
Enhances Spotify data with album cover art and artist metadata (members, collaborators, label) from MusicBrainz and Cover Art Archive.
Provides tools to query and analyze personal Spotify streaming history, including top artists, dormant artists, yearly reviews, and album rankings.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@urmusic-mcp Show me my top artists from 2023 by minutes listened"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
urmusic-mcp
Un MCP personal sobre tu propio historial de Spotify. Corre 100% en tu máquina — tu JSON nunca sale de tu disco, nunca se sube a ningún servidor.
1. Pide tu historial a Spotify
Baja hasta "Descarga tus datos" y marca "Historial de streaming extendido" (no el básico — ese solo trae el último año)
Confirma por email. Spotify tarda entre unos días y unas semanas en mandarte un ZIP.
Descomprime el ZIP en una carpeta — dentro verás varios
Streaming_History_Audio_*.json.
Related MCP server: TuneTidy
2. Instala
Necesitas uv:
git clone https://github.com/ipaud/urmusic-mcp
cd urmusic-mcp
uv sync3. Genera tu base de datos local
uv run ingest.py ./ruta/a/la/carpeta/descomprimidaEsto crea listening.db en el proyecto. Está en .gitignore — nunca la
subas a ningún sitio, es tu historial personal.
4. Conéctalo a Claude
Con Claude Code:
claude mcp add musica -- uv run --directory /ruta/absoluta/a/urmusic-mcp server.pyCon Claude Desktop, añade a tu config MCP:
{
"mcpServers": {
"musica": {
"command": "uv",
"args": ["run", "--directory", "/ruta/absoluta/a/urmusic-mcp", "server.py"]
}
}
}Reinicia y pregunta algo como:
"¿Qué artistas escuché con atención y dejé tirados hace 5 años?"
"Top 10 por convicción, no por reproducciones"
"Recomiéndame música nueva basada en mis semillas de más convicción"
Qué hace cada tool
Tool | Qué hace |
| Esquema de la base de datos |
| SQL de solo lectura sobre tu historial |
| Artistas escuchados con atención y abandonados hace X años, con carátulas |
| Candidatos nuevos vía MusicBrainz (miembros, colaboradores, sello), con carátulas |
| Perfil completo de un artista: plays, convicción, rango temporal, carátula del álbum más escuchado |
| Top artistas de un año por minutos escuchados, con carátulas |
| Top álbumes por reproducciones, con carátulas |
Las carátulas vienen de MusicBrainz + Cover Art Archive y van activadas por
defecto (with_art=true) en los tools que devuelven varios artistas/álbumes.
Cada una cuesta 2 llamadas a MusicBrainz a 1 req/seg, así que listas largas
tardan más — pon with_art=false si prefieres respuesta rápida sin imágenes.
Privacidad
Nada de esto llama a ningún servidor tuyo ni de terceros excepto MusicBrainz y Cover Art Archive (solo nombres de artista/álbum, para buscar relaciones y carátulas — nunca tu historial).
listening.dbvive solo en el disco de quien lo genera.Si compartes este repo, comparte el código — nunca tu
.db.
Licencia
Available Tools
7 toolslistening_artist_profileA
Perfil de escucha completo de un artista: plays, minutos, temas distintos, álbumes explorados, rango temporal, score de convicción y carátula del álbum más escuchado.
Inputs: params (required).
listening_expand_artistA
Expande un artista semilla vía MusicBrainz: miembros, colaboradores y, opcionalmente, compañeros de sello. Para encontrar música nueva conectada a lo que ya te ha convencido, no solo lo que el algoritmo de Spotify sugiere.
Inputs: params (required).
listening_find_dormantB
Encuentra artistas escuchados con atención (alta finalización, varios temas) y luego abandonados hace X años. El lead clásico de 'lo probé, me gustó, corté el hábito'.
Inputs: params (required).
listening_queryA
Ejecuta una consulta SQL de solo lectura contra el historial de escucha. Rechaza cualquier cosa que no empiece por SELECT.
Inputs: params (required). Returns: result
listening_schemaA
Devuelve el esquema de la base de datos (tablas y columnas). Llama esto primero si vas a escribir SQL a mano con listening_query.
Inputs: no named parameters. Returns: result
listening_top_albumsA
Top álbumes por número de reproducciones, con minutos totales. Para responder 'qué disco he escuchado más', a diferencia de listening_year_in_review que agrupa por artista.
Inputs: params (required).
listening_year_in_reviewB
Top artistas de un año concreto por minutos escuchados, con temas distintos. Para ver qué dominó tu año o comparar la evolución entre años.
Inputs: params (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Each tool targets a clearly distinct purpose: raw SQL querying, dormant artist discovery, artist expansion via MusicBrainz, artist profile, yearly review, top albums, and schema introspection. Even listening_year_in_review vs listening_top_albums are explicitly disambiguated in their descriptions (grouping by artist vs album).
All tools follow a consistent listening_verb_noun pattern (query, find_dormant, expand_artist, artist_profile, year_in_review, top_albums, schema). The verb_noun structure is uniform and predictable throughout.
Seven tools is a well-scoped set for a listening-history MCP server. Each tool earns its place: data access, schema introspection, and several distinct analytical/exploratory queries.
The surface covers the main listening-history use cases well: raw querying, artist profiles, top albums, yearly review, dormant-artist leads, and artist expansion. A minor gap is the lack of a broader 'top artists all-time' tool independent of a specific year, though listening_query could cover it.
Related MCP Connectors
An MCP server that gives your AI access to the source code and docs of all public github repos
An MCP server that provides read access to your cloud storage providers, bank accounts and more.
Search your AI chat history (ChatGPT, Claude, Codex) from any MCP client. Remote, private, read-only
Related MCP Servers
- FlicenseAqualityDmaintenanceA lightweight MCP server that enables AI assistants like Cursor and Claude to control Spotify playback, playlists, and manage tokens via OAuth.152-
- FlicenseNot gradedqualityDmaintenanceAn MCP server that enables ChatGPT to control Spotify playlists, playback (including exact-cue seek), and perform offline metadata export to ZIP.1-
- FlicenseNot gradedqualityCmaintenanceA lightweight MCP server that enables AI assistants to control Spotify playback and manage playlists.-
- FlicenseBqualityDmaintenanceA local music retrieval MCP server that lets users search, download, and organize songs via natural language, with lyrics matching from NetEase Cloud Music and LRCLIB, plus local library indexing through SQLite.5-