Skip to main content
Glama

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

  1. Ve a privacy.spotify.com/es/account/privacy

  2. Baja hasta "Descarga tus datos" y marca "Historial de streaming extendido" (no el básico — ese solo trae el último año)

  3. Confirma por email. Spotify tarda entre unos días y unas semanas en mandarte un ZIP.

  4. 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 sync

3. Genera tu base de datos local

uv run ingest.py ./ruta/a/la/carpeta/descomprimida

Esto 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.py

Con 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

listening_schema

Esquema de la base de datos

listening_query

SQL de solo lectura sobre tu historial

listening_find_dormant

Artistas escuchados con atención y abandonados hace X años, con carátulas

listening_expand_artist

Candidatos nuevos vía MusicBrainz (miembros, colaboradores, sello), con carátulas

listening_artist_profile

Perfil completo de un artista: plays, convicción, rango temporal, carátula del álbum más escuchado

listening_year_in_review

Top artistas de un año por minutos escuchados, con carátulas

listening_top_albums

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.db vive solo en el disco de quien lo genera.

  • Si compartes este repo, comparte el código — nunca tu .db.

Licencia

MIT

Available Tools

7 tools
listening_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

    A4/5.0

    Scored across 7 tools

    Disambiguation5/5

    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).

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    Related MCP Servers

    • F
      license
      A
      quality
      D
      maintenance
      A lightweight MCP server that enables AI assistants like Cursor and Claude to control Spotify playback, playlists, and manage tokens via OAuth.
      15
      2
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that enables ChatGPT to control Spotify playlists, playback (including exact-cue seek), and perform offline metadata export to ZIP.
      1
      -
    • F
      license
      B
      quality
      D
      maintenance
      A 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
      -