# Spotify Listening History Parser MCP > The Spotify Listening History Parser takes your massive Spotify data dump—the raw JSON file you get from Privacy settings—and cleans it up for you. It processes millions of plays to generate actionable insights: your top 30 artists, your top 30 tracks, and the exact total hours you spent listening. Your AI client reads this structured data locally. ## Overview - **Category:** industry-titans - **Price:** Free - **Tags:** data-parsing, music-analytics, listening-history, json-processing, personal-data, media-consumption ## Description You know that raw Spotify data dump you get from their privacy settings? It’s massive—millions of individual records, just sitting there as unformatted JSON. Trying to make sense of all those plays yourself is a nightmare. That's where the `parse_spotify_history` tool steps in. This MCP server takes that huge Spotify JSON export and cleans it up for you. It doesn't just dump data; it processes millions of individual play events to generate clean, actionable metrics right on your machine. Your AI client reads this structured data locally—meaning all your music history stays private, which is a major win. The core mechanism is simple: the `parse_spotify_history` tool accepts your Spotify listening history JSON export and figures out what you're really into. It doesn't just count songs; it builds specific rankings for you based on the raw play counts in the file. You get back three critical pieces of information that are way easier to use than the original data. First, regarding your taste: The tool processes the entire history file and returns a ranked list showing your top 30 most played artists. It figures out which thirty names dominate your listening habits over time. Second, it aggregates all the tracks into identifying your top 30 most streamed songs across every single play session. You get a clear ranking of exactly what tunes you keep spinning. It also determines your total listening hours. Based on the raw play count in your history file, the parser calculates the precise cumulative number of hours you spent listening to music on Spotify. This isn't just a rough estimate; it’s a calculation based on the recorded activity. The output is always structured data, making it easy for your AI client to read and use immediately. Because this process happens locally with `parse_spotify_history`, you don't have to upload any sensitive music data anywhere else. It takes the unstructured chaos of millions of play records and turns it into three clean, manageable metrics: top artists, top tracks, and total elapsed listening hours. ## Tools ### parse_spotify_history Accepts a Spotify JSON export and returns aggregated top 30 lists for artists and tracks, plus total listening hours. ## Prompt Examples **Prompt:** ``` What was my most listened artist in 2024? ``` **Response:** ``` Your #1 artist was Radiohead with 342 plays, followed by Tame Impala (218) and Daft Punk (195). ``` **Prompt:** ``` How many total hours did I spend on Spotify? ``` **Response:** ``` You spent exactly 1,245.3 hours listening to music across 28,400 tracks. ``` **Prompt:** ``` Show my top 5 most played songs of all time. ``` **Response:** ``` 1. Bohemian Rhapsody — Queen (89 plays) 2. Blinding Lights — The Weeknd (76) 3. Creep — Radiohead (71) ``` ## Capabilities ### Calculate Top Artists The tool processes your history file and returns a ranked list of your top 30 most played artists. ### Find Top Tracks It aggregates the data to identify your top 30 most streamed songs across all time. ### Determine Total Listening Hours The parser calculates the precise total number of hours you spent on Spotify based on the raw play count. ## Use Cases ### Figuring out why you spent so much time listening to one genre. You realize you've been stuck in a musical rut. You run the `parse_spotify_history` tool on your export. The output shows that 60% of your total hours came from three bands, letting you know exactly where your consumption habits are focused. ### Building a profile for a client based on their tastes. You need to pitch music recommendations. You feed the raw history into `parse_spotify_history`. The resulting top 30 artists and tracks give you immediate, data-backed proof of the user's specific aesthetic. ### Calculating lifetime usage metrics. You need to report total platform engagement. By running `parse_spotify_history`, your agent gets the exact number of total listening hours and unique track counts, perfect for quarterly reports. ## Benefits - You get precise numbers, not guesses. The `parse_spotify_history` tool calculates your exact total listening hours and provides accurate counts for unique tracks streamed, eliminating guesswork about usage. - The output is structured for immediate use. Instead of sifting through millions of rows of JSON, you instantly receive clean top-30 rankings for both artists and songs that the parser handles. - It keeps your data private. Because parsing happens locally after you provide the file, you don't risk sending sensitive listening patterns to a third party just for simple analysis. - The insights are actionable. You can immediately ask: 'Who was my #1 artist?' and get a direct answer backed by the `parse_spotify_history` tool output. - It works on bulk data. This isn't just for your last 50 songs; it processes years of history, giving you comprehensive views of consumption habits. ## How It Works The bottom line is that it takes messy streaming logs and gives you clear, ranked metrics about your music consumption. 1. You feed your massive, raw Spotify listening history JSON export into the `parse_spotify_history` tool. 2. The MCP runs the data through its aggregation engine to calculate counts for artists, tracks, and time spent. 3. Your AI client receives a clean summary containing top 30 lists, total hours, and unique track counts. ## Frequently Asked Questions **How do I get my Spotify data?** Go to spotify.com/account/privacy. Request your data. Spotify emails you a download link within 30 days. **Does it work with Apple Music?** This parser is optimized for Spotify's JSON format. Apple Music exports use a different structure. **Is my listening data sent to the cloud?** No. All aggregation happens locally. Only the top-30 lists and totals are sent to the AI. **What format should I use when running the `parse_spotify_history` tool?** The tool requires a single, valid JSON array containing your raw listening event objects. You must source this file from Spotify’s official Privacy or Takeout export; manually compiled data won't work. **How does `parse_spotify_history` handle massive Spotify data exports?** Since the processing runs locally, it handles large volumes of records efficiently. Processing time depends directly on the total size and complexity of the JSON file you pass into the tool. **What kind of structured metrics does `parse_spotify_history` provide?** It returns actionable, aggregated data points. These include your top 30 most played artists, your top 30 tracks, and a precise total calculation of all listening hours. **What happens if my Spotify JSON export is corrupted or empty?** If the source JSON file is malformed or lacks content, the tool will generate a specific parsing error. Always validate your data source before attempting to run `parse_spotify_history`. **Are there any limitations on the time range when I use `parse_spotify_history`?** The tool processes everything contained within the JSON file; it doesn't enforce a date limit. However, if your export only covers certain periods, the metrics will accurately reflect that limited scope.