Skip to main content
Glama
Sign In
Your Spotify MCP Server

Your Spotify MCP Server

by pentafive
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

Your Spotify MCP Server

CI License: Apache 2.0 Node.js

A Model Context Protocol (MCP) server that connects AI assistants to Your Spotify's analytics API and Spotify's Web API.

Requires: A self-hosted Your Spotify instance for unlimited listening history analytics.

Why This MCP Server?

Feature

Spotify API

Your Spotify MCP

Listening history

Last 50 tracks

Unlimited

Custom time ranges

No

Yes (any period)

Play count stats

No

Yes

Collaborative analytics

No

Yes (affinity)*

Custom Wrapped

Annual only

Any time period

*Affinity analysis requires authenticated web session; see Known Issues

Related MCP server: Spotify MCP Node Server

Features

Tier 1: Core Analytics (Your Spotify API)

  • get_track_stats - Detailed listening statistics for any track

  • get_top_tracks - Top tracks for any time period

  • get_top_artists - Top artists for any time period

  • get_artist_stats - Artist listening patterns

  • search_listening_history - Search your complete history

Tier 2: Enhanced Analytics

  • create_custom_wrapped - Spotify Wrapped for ANY time period

  • analyze_affinity - Collaborative listening analysis

  • get_listening_timeline - Timeline of listening activity

  • get_artist_rank - Your ranking for an artist

  • get_track_rank - Your ranking for a track

Tier 3: Power Analytics

  • analyze_listening_patterns - Peak listening times, habits

  • get_discovery_insights - New music discoveries

  • compare_listening_periods - Period-over-period comparisons

  • export_listening_data - Export in JSON, CSV, or summary format

Tier 4: Account Management

  • get_listening_summary - Overview of listening habits

  • update_user_settings - Manage account settings

  • generate_public_share_link - Share your stats

Tier 5: Spotify Control (Optional)

Requires Spotify API credentials - see setup below

  • control_playback - Play, pause, skip, seek

  • manage_playlist - Create and modify playlists

  • search_spotify - Search Spotify catalog

Note: Tiers 1-4 (18 tools) work with just Your Spotify. Tier 5 (10 additional tools) requires separate Spotify Web API credentials.

Token-Efficient Output (TOON)

This server supports TOON (Token-Oriented Object Notation) for 40-60% token savings on list responses.

# JSON output (verbose)
{"tracks": [{"name": "Song A", "artist": "Artist 1", "plays": 42}, ...]}

# TOON output (compact, default)
tracks[10]{name,artist,plays}:
  Song A,Artist 1,42
  Song B,Artist 2,38
  ...

Most tools support an output_format parameter:

  • "toon" (default) - Compact format, ideal for AI assistants

  • "json" - Standard JSON for programmatic use

TOON Resources:

Requirements

  • Node.js 18+

  • Your Spotify instance (self-hosted)

  • Your Spotify public token (from Your Spotify settings)

Setup

1. Install Dependencies

npm install

2. Build

npm run build

3. Get Your Spotify Token

  1. Open your Your Spotify dashboard

  2. Go to Settings

  3. Generate/copy your public token

4. Configure Environment Variables

Required:

  • YOUR_SPOTIFY_API_URL - Your Your Spotify API URL (e.g., 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

5. Configure Claude Desktop

Add to your Claude Desktop config (~/.config/Claude/claude_desktop_config.json on Linux):

{
  "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"
      }
    }
  }
}

More configurations: See examples/ for Claude Code, Gemini, and other client configs.

Usage Examples

Once configured, you can ask Claude:

  • "What are my top 10 tracks?"

  • "Show me my most played songs from summer 2024"

  • "Create my Spotify Wrapped for Q1 2024"

  • "How many times have I listened to [track name]?"

  • "What songs would my partner and I both enjoy?" (affinity)

Development

# Build and watch for changes
npm run watch

# Run in development mode
npm run dev

# Clean build
npm run clean

Architecture

src/
├── index.ts                    # Main entry point, MCP server setup
├── lib/
│   ├── your-spotify-client.ts  # Your Spotify HTTP client
│   ├── spotify-client.ts       # Spotify Web API client
│   └── toon-utils.ts           # TOON format utilities
├── services/
│   └── your-spotify-service.ts # Business logic layer
└── tools/
    ├── tier1/                  # Core analytics
    ├── tier2/                  # Enhanced analytics
    ├── tier3/                  # Power analytics
    ├── tier4/                  # Account management
    └── tier5/                  # Spotify control

Roadmap

Completed (v0.2.x)

  • Core analytics tools (Tier 1) - 5 tools

  • Enhanced analytics (Tier 2) - Custom Wrapped, Affinity, Rankings

  • Power analytics (Tier 3) - Patterns, Comparisons, Export

  • Account management (Tier 4) - Settings, Sharing

  • TOON format support for token-efficient output

  • Public token authentication

Optional (v0.2.x)

  • Spotify playback control (Tier 5) - Requires Spotify API credentials

Future

  • Dedicated API token authentication (contribution to Your Spotify upstream)

  • Enhanced rate limiting

  • WebSocket support for real-time updates

Related Projects

Documentation

Contributing

See CONTRIBUTING.md for guidelines.

Security

See SECURITY.md for vulnerability reporting.

License

Apache 2.0 - See LICENSE for details.

Available Tools

18 tools
analyze_affinityA

Analyze listening overlap between multiple Your Spotify users.

Find songs that multiple users share in common - perfect for:

  • Creating collaborative playlists

  • Road trip music everyone enjoys

  • Party playlists where everyone knows the songs

  • Understanding shared music tastes with friends

Two analysis modes:

  • minima: Songs EVERYONE has listened to (highest overlap)

    • Good for: "Songs we ALL know"

    • Score based on lowest listener's play count

  • average: Songs that satisfy SOME people a lot

    • Good for: "Songs someone will love"

    • Score based on average play count

Example queries:

  • "What songs do my girlfriend and I both like?"

  • "Find music that everyone at the party knows"

  • "What's our shared music taste?"

Inputs: user_ids (required), mode, limit, start_date, +1 more.

analyze_listening_patternsB

Analyze your listening patterns over time.

Discover when you listen to music most - by hour of day, day of week, or month.

Example queries:

  • "What time of day do I listen to music most?"

  • "Which day of the week has the most plays?"

  • "Am I a morning or evening listener?"

Inputs: pattern_type, start_date, end_date.

compare_listening_periodsA

Compare your listening habits between two time periods.

See how your listening volume, diversity, and preferences have changed.

Example queries:

  • "Compare my listening in summer 2024 vs summer 2023"

  • "How did my music habits change from Q1 to Q2?"

  • "Am I listening more this year than last year?"

Inputs: period1_start (required), period1_end (required), period2_start (required), period2_end (required).

create_custom_wrappedA

Generate a custom Spotify Wrapped summary for ANY time period.

Unlike Spotify's official Wrapped (limited to the past year), this creates personalized listening summaries for any date range you choose.

Perfect for:

  • Seasonal summaries ("My Summer 2024 Wrapped")

  • Event-based recaps ("Music during my vacation")

  • Comparative analysis ("This semester vs last semester")

  • Monthly or weekly reviews

Returns comprehensive statistics including:

  • Total listening time and track counts

  • Top 5 tracks, artists, and albums

  • Listening patterns (peak hours, days)

  • New music discoveries in that period

Example queries:

  • "Create my Spotify Wrapped for summer 2024"

  • "What did my music look like during my road trip in March?"

  • "Generate a wrapped for the first half of 2024"

  • "Show me my December listening stats"

Inputs: start_date (required), end_date (required).

export_listening_dataC

Export your listening data in various formats.

Get a structured export of your listening history, top tracks, artists, etc.

Example queries:

  • "Export my 2024 listening stats"

  • "Give me a summary of my listening data"

  • "Export my top 100 tracks as JSON"

Inputs: start_date, end_date, format, include, +1 more.

generate_public_share_linkA

Generate a public link to share your Your Spotify statistics.

Anyone with this link can view your listening history without logging in. Use revoke_public_access to disable the link when you're done sharing.

Example queries:

  • "Create a public link to share my 2024 stats"

  • "Generate a shareable link for my profile"

Inputs: description.

get_artist_rankA

Find where a specific artist ranks in your listening history.

Shows the artist's position among all artists you've listened to, along with percentile ranking.

Example queries:

  • "Where does Radiohead rank in my listening?"

  • "Is Taylor Swift in my top 10?"

  • "What's my percentile for The Beatles?"

Inputs: artist_id (required), start_date, end_date.

get_artist_statsA

Get detailed listening statistics for a specific artist from your listening history.

Returns information including:

  • Total play count across all their tracks

  • Total listening time

  • First and last time you played any of their tracks

  • Your top tracks by this artist

Example queries:

  • "How much have I listened to Radiohead?"

  • "What are my top songs by The Weeknd?"

  • "When did I first discover NF?"

Inputs: artist_id (required).

get_discovery_insightsA

Discover new music you found in a specific time period.

Shows tracks and artists you listened to for the first time during the period.

Example queries:

  • "What new music did I discover in 2024?"

  • "Show me artists I found this summer"

  • "What were my new discoveries last month?"

Inputs: start_date (required), end_date, limit.

get_listening_timelineB

Analyze your listening activity over time.

Returns a timeline of plays and listening duration at day, week, or month granularity.

Example queries:

  • "Show my listening timeline for 2024"

  • "How has my listening changed month over month?"

  • "What were my most active listening days last summer?"

Inputs: start_date, end_date, granularity.

get_top_artistsB

Get your top artists for a specified time period.

Returns artists ranked by play count including:

  • Artist name and Spotify ID

  • Total play count

  • Total listening time

Example queries:

  • "Who are my top 10 artists this year?"

  • "What artists did I listen to most in summer 2024?"

  • "Show me my all-time top 20 artists"

Inputs: start_date, end_date, limit.

get_top_tracksA

Get your most played tracks for any time period.

Returns your top tracks ranked by play count, with full track details and play statistics. This queries your complete listening history (not limited to Spotify's 50 recent tracks).

Time period options:

  • Omit dates for all-time top tracks

  • Specify start_date only for "since X" queries

  • Specify both dates for a specific range

Example queries:

  • "What are my top 10 songs?"

  • "What were my most played tracks in summer 2024?"

  • "Show me my top 20 songs from last month"

  • "What are my all-time top tracks?"

Inputs: start_date, end_date, limit, output_format.

get_track_rankA

Find where a specific track ranks in your listening history.

Shows the track's position among all tracks you've listened to, along with percentile ranking.

Example queries:

  • "Where does Bohemian Rhapsody rank in my plays?"

  • "Is this song in my top 100?"

  • "What percentile is Blinding Lights in my history?"

Inputs: track_id (required), start_date, end_date.

get_track_statsA

Get detailed listening statistics for a specific track from your listening history.

Returns information including:

  • Total play count across all time

  • Total listening time

  • First and last time you played the track

  • Average plays per day

  • Your peak listening day for this track

Example queries:

  • "How many times have I listened to Bohemian Rhapsody?"

  • "When did I first listen to this song?"

  • "What's my most played day for this track?"

Inputs: track_id (required).

rename_accountA

Change your display username in Your Spotify.

This only affects your Your Spotify profile, not your actual Spotify account.

Example queries:

  • "Change my username to JonDown"

  • "Rename my account to MusicFan2024"

Inputs: new_username (required).

revoke_public_accessA

Revoke your public share token, immediately disabling the public link.

Use this when you no longer want your stats publicly accessible.

Example queries:

  • "Revoke my public share link"

  • "Disable public access to my stats"

  • "Remove my public profile"

Inputs: no named parameters.

search_listening_historyB

Search through your complete Spotify listening history.

Unlike Spotify's recent tracks (limited to 50), this searches your ENTIRE history stored in Your Spotify.

Example queries:

  • "Find all times I listened to Radiohead"

  • "Search for songs with 'love' in the title"

  • "When did I listen to OK Computer?"

Inputs: query (required), type, start_date, end_date, +1 more.

update_user_settingsB

Update your Your Spotify account settings.

Currently supports updating timezone preferences.

Example queries:

  • "Set my timezone to Pacific Time"

  • "Change my timezone to Europe/London"

Inputs: timezone.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A3.7/5.0

    Scored across 18 tools

    Disambiguation4/5

    Most tools have distinct purposes, such as analyze_affinity for user overlap and get_top_tracks for ranking tracks. However, some overlap exists between get_artist_stats and get_artist_rank, which both focus on artist-specific data, potentially causing confusion. The descriptions help differentiate them, but the boundaries could be clearer.

    Naming Consistency5/5

    All tool names follow a consistent snake_case pattern with clear verb_noun structures, such as analyze_affinity, get_top_tracks, and update_user_settings. There are no deviations in naming conventions, making the set predictable and easy to navigate.

    Tool Count4/5

    With 18 tools, the count is slightly high but reasonable for a Spotify analytics server covering user stats, sharing, and account management. It includes core functionalities like analysis, ranking, and export, though it might feel a bit heavy compared to more focused servers.

    Completeness5/5

    The toolset provides comprehensive coverage for Spotify listening analytics, including analysis, ranking, history search, data export, sharing, and account settings. There are no obvious gaps; it supports full lifecycle operations from data retrieval to user customization and public sharing.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers

    • spotify-mcp

      sjtan2302
      A
      license
      A
      quality
      C
      maintenance
      Lets AI assistants answer questions about your Spotify listening history, including taste evolution, top artists, recently played, and playlist analysis.
      8
      133 npm
      MIT