Your Spotify

Provides analytics and control via MCP for Your Spotify data, with multi-tier insights and optional Spotify playback control.

typescript

GitHub Stars

typescript

Language

5 months ago

First Indexed

2 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "pentafive-your-spotify-mcp": {
      "command": "node",
      "args": [
        "/path/to/your-spotify-mcp/build/index.js"
      ],
      "env": {
        "SPOTIFY_CLIENT_ID": "YOUR_SPOTIFY_CLIENT_ID",
        "YOUR_SPOTIFY_TOKEN": "your_public_token_here",
        "SPOTIFY_ACCESS_TOKEN": "YOUR_SPOTIFY_ACCESS_TOKEN",
        "YOUR_SPOTIFY_API_URL": "https://your-spotify-api.example.com",
        "SPOTIFY_CLIENT_SECRET": "YOUR_SPOTIFY_CLIENT_SECRET",
        "SPOTIFY_REFRESH_TOKEN": "YOUR_SPOTIFY_REFRESH_TOKEN"
      }
    }
  }
}

You run a self-hosted MCP server that bridges your Spotify data with AI assistants. It unlocks deep analytics on your listening history, lets you generate custom Wrapped periods, compares listening across time, and (optionally) controls playback and manages playlists through Spotify credentials. This setup helps you get fast, token-efficient insights and seamless integration with Claude Desktop or other MCP clients.

How to use

After you have the MCP server running, you can ask your AI assistant for analytics like your top tracks, custom time-window Wrapped reports, listening timelines, and affinity with other users. You can request practical insights such as peak listening times, new music discoveries, and period-over-period comparisons. If you configure the optional Spotify credentials, you can also control playback, create and modify playlists, and search the Spotify catalog.

How to install

Prerequisites: you need Node.js 18 or newer and a self-hosted Your Spotify instance with a public token.

Install dependencies

npm install

Build the MCP server

npm run build

Get Your Spotify token

Open your Your Spotify dashboard, go to Settings, then generate or copy your public token.

Configure environment variables

Required:

YOUR_SPOTIFY_API_URL - Your Your Spotify API URL (for example, https://your-spotify-api.example.com)
YOUR_SPOTIFY_TOKEN - Your public token from Your Spotify

Optional (for Tier 5 features):

SPOTIFY_CLIENT_ID - Spotify App Client ID
SPOTIFY_CLIENT_SECRET - Spotify App Client Secret
SPOTIFY_ACCESS_TOKEN - Spotify OAuth Access Token
SPOTIFY_REFRESH_TOKEN - Spotify OAuth Refresh Token

Configure Claude Desktop

{
  "mcpServers": {
    "your-spotify": {
      "command": "node",
      "args": ["/path/to/your-spotify-mcp/build/index.js"],
      "env": {
        "YOUR_SPOTIFY_API_URL": "https://your-spotify-api.example.com",
        "YOUR_SPOTIFY_TOKEN": "your_public_token_here"
      }
    }
  }
}

Additional notes and setup tips

You can run the server in development mode if you prefer live-reload during development. The build produces a runnable index that you reference from your local MCP client configuration.

Usage examples

Ask your AI assistant for insights like: top 10 tracks, most played songs from a specific period, a custom Wrapped for a given quarter, or how many times you listened to a particular track.

Architecture

The server includes a core HTTP client to Your Spotify, a Web API client for Spotify, and a business logic layer that exposes analytics through tiered tools. It outputs data in a token-efficient format by default and supports a compact TOON representation for AI-friendly responses.

Security and tokens

Secure handling relies on your Your Spotify public token and, when enabled, Spotify API credentials for Tier 5 features. Keep tokens secret and rotate them periodically according to your security practices.

Available tools

get_track_stats

Detailed listening statistics for a specific track across defined periods.

get_top_tracks

Top tracks for a chosen time window.

get_top_artists

Top artists for a given period.

get_artist_stats

Artist listening patterns and trends.

search_listening_history

Search the complete listening history.

create_custom_wrapped

Generate Spotify Wrapped-style reports for any time period.

analyze_affinity

Collaborative listening analysis to find shared tastes.

get_listening_timeline

Timeline of listening activity.

get_artist_rank

Your ranking for an artist.

get_track_rank

Your ranking for a track.

analyze_listening_patterns

Identify peak listening times and habits.

get_discovery_insights

New music discoveries based on listening patterns.

compare_listening_periods

Period-over-period comparisons of listening activity.

export_listening_data

Export listening data as JSON, CSV, or a summary.

get_listening_summary

Overview of listening habits.

update_user_settings

Manage account settings.

generate_public_share_link

Share your stats with others.

control_playback

Play, pause, skip, and seek on Spotify.

manage_playlist

Create and modify playlists.

search_spotify

Search the Spotify catalog.

Built by

VeilStrat

AI signals for GTM teams