Spotify Listening History Parser MCP for AI. Turn raw song logs into clear music metrics.

Claude

ChatGPT

Cursor

Gemini

Windsurf

VS Code

JetBrains

Vercel

See Vinkius in Action

Works with every AI agent you already use

…and any MCP-compatible client

Connect to your AI in seconds.

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.

What your AI can do

Parse spotify history

Accepts a Spotify JSON export and returns aggregated top 30 lists for artists and tracks, plus total listening hours.

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.

Ask an AI about this

Included with Plan

Waiting for input…

AI Agent

Spotify Listening History Parser MCP Server: 1 Tool for Analytics

The single tool here processes your Spotify JSON export to calculate quantitative music consumption data.

Make your AI actually useful.

Add this MCP to Claude, Cursor, or Windsurf and your AI stops guessing. It gets real tools to look things up, take action, and handle the stuff you keep doing by hand.

Start using Spotify Listening History Parser on Vinkius

Parse Spotify History

Accepts a Spotify JSON export and returns aggregated top 30 lists for artists and tracks, plus total listening hours.

Security and governance baked right in.

Pick your AI client below to get set up. Just create a Vinkius account, subscribe, and you're instantly up and running. We handle the entire backend infrastructure, delivering out-of-the-box support for HTTPS Streamable, SSE, and OAuth2—zero messy routing required.

Claude AI

Open Claude Settings

Go to claude.ai, click your profile icon, then navigate to Customize → Connectors.

Add Custom Connector

Click the "+" button and select Add custom connector. Paste your Vinkius endpoint URL:

https://edge.vinkius.com/[YOUR_TOKEN_HERE]/mcp

Replace [YOUR_TOKEN_HERE] with your token from cloud.vinkius.com. For OAuth-protected servers, expand Advanced settings to add credentials.

Start a conversation

Open a new chat. The Spotify Listening History Parser integration is available immediately — no restart needed.

Antigravity

Configure Agent Environment

Open your Antigravity agent's workspace configuration or mcp-servers.json file.

Bind the Endpoint

Add the Vinkius endpoint URL to your agent's MCP connections list:

"mcp_servers": {
  "spotify-listening-history-parser": {
    "serverUrl": "https://edge.vinkius.com/[YOUR_TOKEN_HERE]/mcp"
  }
}

Provide your secure token in place of [YOUR_TOKEN_HERE] to ensure your agent requests are authenticated.

Execute

Start your Antigravity session. The agent will autonomously discover and utilize the Spotify Listening History Parser tools with full Vinkius guardrails applied.

VS Code Copilot

⚡

One-Click Install (Recommended)

In your Vinkius Dashboard, simply click the Add to VS Code button for this server. We'll automatically configure your local workspace.

Or configure manually

Open MCP Settings

Open VS Code, press Ctrl/Cmd + Shift + P, and search for GitHub Copilot: MCP Servers.

Add Server Config

Add the Vinkius endpoint configuration to your mcp-servers.json file:

"spotify-listening-history-parser": {
  "url": "https://edge.vinkius.com/[YOUR_TOKEN_HERE]/mcp"
}

Ensure you replace [YOUR_TOKEN_HERE] with your token from cloud.vinkius.com.

LangChain

Install Dependencies

Install the LangChain MCP adapters for your environment:

pip install langchain-mcp-adapters

Connect the Server

Use the SSEClient in LangChain to connect to the Vinkius managed endpoint:

from langchain_mcp_adapters.client import SSEClient

# Connect to Vinkius
client = SSEClient(url="https://edge.vinkius.com/[YOUR_TOKEN_HERE]/mcp")
tools = client.get_tools()

CrewAI

Define the Tool

Load the Vinkius MCP tools into your CrewAI agents:

from crewai import Agent
from mcp_crewai import MCPTool

# Connect securely to Vinkius
vinkius_tools = MCPTool(url="https://edge.vinkius.com/[YOUR_TOKEN_HERE]/mcp")

# Assign to Agent
researcher = Agent(
    role='Data Researcher',
    tools=vinkius_tools.get_all()
)

Execute Task

Run your CrewAI process. The agent will autonomously route tasks to the Vinkius managed server.

Choose How to Get Started

Build a custom MCP for your own tools, or connect a ready-made integration from our catalog.

Build Your Own

Turn any API into an MCP. Import a spec, define Agent Skills, or deploy with MCPFusion.

Import from OpenAPI, Swagger, or YAML specs
Create Agent Skills with progressive disclosure
Deploy to edge with MCPFusion framework
Built in DLP, auth, and compliance on every call
Real time usage dashboard and cost metering
Publish to catalog or keep private

Start building

Make Your AI Do More

Start with Spotify Listening History Parser, then connect any of our 5,100+ other servers whenever your AI needs more. One click, no limits.

Use this MCP plus 5,100+ others, all in one place
Add new capabilities to your AI anytime you want
Every connection is secured and compliant automatically
Track usage and costs across all your servers
Works with Claude, ChatGPT, Cursor, and more
New servers added to the catalog every week

Spotify Listening History Parser MCP server cover

Independent Platform Disclaimer: Vinkius is an independent platform and is not affiliated with, endorsed by, sponsored by, verified by, or otherwise authorized by spotify-privacy. All third-party trademarks, logos, and brand names are the property of their respective owners. Their use on this website is strictly for informational purposes to identify service compatibility and interoperability.

VINKIUS INFRASTRUCTURE

Cloud Hosted

Managed infra

V8 Isolated

Sandboxed per request

Zero-Trust Proxy

No stored credentials

DLP Enforced

Policy on every call

GDPR Compliant

EU data residency

Token Compression

~60% cost reduction

Your data is protected. See how we built it.

Works with Claude, ChatGPT, Cursor, and more

The Model Context Protocol standardizes how applications expose capabilities to LLMs. Instead of operating in isolation, your AI gains direct access to external platforms, live data, and real-world actions through secure, standardized connections.

This connection provides 1 powerful capabilities that interface natively with Claude, ChatGPT, Cursor, and other compatible AI platforms. No middleware. No custom integration required.

Sifting through millions of lines of raw listening logs is a pain.

Right now, getting actual metrics means downloading a massive JSON file. You're staring at fields like `duration`, `played_at`, and `artist_name`—millions of them. To figure out your top artists or total hours, you have to write code, filter by date ranges, count unique entries, and then manually calculate the totals. It’s a multi-step process that takes time and breaks if Spotify tweaks its format.

With this MCP server, you just feed the raw file into `parse_spotify_history`. Your agent runs it once, and the output is clean: top 30 artists, top 30 tracks, and your total listening hours. The effort goes from writing a full script to one simple data call.

Spotify Listening History Parser MCP Server: Get metrics in plain English.

You no longer need to open up VS Code, set up virtual environments, and write complex aggregation queries just to answer a simple question like 'How long did I listen last year?' The tool handles the heavy lifting of data structure parsing, counting, and ranking all in one go.

It's a direct read. You get clear numbers—the total hours, the top acts—without touching any code or dealing with messy JSON syntax. It just works.

Support 24/7 support@vinkius.com ↗

Security Vinkius Trust Center ↗

SLA Service Level Agreement ↗

Report Listing Send Report ↗

What your AI can actually do with this

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.

Built · Hosted · Managed by Vinkius Spotify Listening History Parser - Music Metrics

Server ID 019e38f1-3c46-7370-8cd6-60f71ce5b7c1

Vinkius Inspector

Compliance Grade A+

Score 100/100

Report View Report ↗

Here's how it actually works

The bottom line is that it takes messy streaming logs and gives you clear, ranked metrics about your music consumption.

You feed your massive, raw Spotify listening history JSON export into the parse_spotify_history tool.

The MCP runs the data through its aggregation engine to calculate counts for artists, tracks, and time spent.

Your AI client receives a clean summary containing top 30 lists, total hours, and unique track counts.

Who is this actually for?

Anyone who treats their personal data seriously but gets bored manually digging through raw JSON files. This is for the researcher needing quantifiable proof of taste, the marketing analyst mapping consumer behavior, or just the casual user who wants to know if they've been stuck listening to one album for six months.

Data Analyst

They feed raw streaming data into parse_spotify_history to quantify niche cultural trends or calculate engagement metrics over time.

Content Strategist

They use the top artist and track lists from the parser to inform content creation, knowing what kind of music resonates with a specific user base.

Media Researcher

They need quick metrics—like total listening hours or genre trends—without having to write complex Python scripts for data aggregation.

What Changes When You Connect

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.

See it in action

01 01

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.

02 02

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.

03 03

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.

The honest tradeoffs

Writing a script to count plays.

Anti-pattern

Trying to write custom Python code every time you want to check top artists. This is tedious, breaks when Spotify changes its JSON format, and takes hours of debugging.

The Fix

Just use the parse_spotify_history tool. It handles the data structure and aggregation logic for you in one call.

Relying on memory or simple screenshots.

Anti-pattern

Remembering that your favorite artist was 'X' because you saw it once, rather than checking the actual play count. This leads to inaccurate analysis and guesswork.

The Fix

Always run parse_spotify_history. It gives quantified proof of consumption, letting you know exactly how many times an artist or track played.

Using partial data sets.

Anti-pattern

Only running the parser on last month's worth of history. This skews your view and doesn't give a true picture of long-term taste evolution.

The Fix

Make sure you feed the full, complete JSON export into parse_spotify_history. The tool is designed to aggregate across entire data periods.

When It Fits, When It Doesn't

Use this server if your goal is pure quantitative analysis of streaming consumption. Specifically, if you need a ranked list of top artists or tracks, or an exact calculation of total listening hours from a large JSON file, the parse_spotify_history tool is built for it.

Don't use this if you are trying to analyze why certain songs were played (e.g., mood correlation) or if you need real-time data—that requires different API connections. Also, don't expect conversational AI magic; you must provide the full JSON export first, and then ask your agent to interpret that structured output.

Questions you might have

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.

Connect to your AI in seconds.

Parse spotify history

Spotify Listening History Parser MCP Server: 1 Tool for Analytics

Make your AI actually useful.

Parse Spotify History

Security and governance baked right in.

Claude AI

Open Claude Settings

Add Custom Connector

Start a conversation

Claude Code

Open your terminal

Add the MCP Server

Start coding

Cursor

One-Click Install (Recommended)

Open Cursor Settings

Add New Server

Use in Composer

Antigravity

Configure Agent Environment

Bind the Endpoint

Execute

VS Code Copilot

One-Click Install (Recommended)

Open MCP Settings

Add Server Config

Windsurf

One-Click Install (Recommended)

Open Windsurf Settings

Add Server Endpoint

LangChain

Install Dependencies

Connect the Server

CrewAI

Define the Tool

Execute Task

Choose How to Get Started

Build Your Own

Make Your AI Do More

Works with Claude, ChatGPT, Cursor, and more

Sifting through millions of lines of raw listening logs is a pain.

Spotify Listening History Parser MCP Server: Get metrics in plain English.

What your AI can actually do with this

Here's how it actually works

Who is this actually for?

What Changes When You Connect

See it in action

Figuring out why you spent so much time listening to one genre.

Building a profile for a client based on their tastes.

Calculating lifetime usage metrics.

The honest tradeoffs

Writing a script to count plays.

Relying on memory or simple screenshots.

Using partial data sets.

When It Fits, When It Doesn't

Questions you might have