Your Spotify MCP Server

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?

*Affinity analysis requires authenticated web session; see

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.

Most tools support an output_format parameter:

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

• "json" - Standard JSON for programmatic use

TOON Resources:

• Website: https://toonformat.dev

• GitHub: https://github.com/toon-format/toon

• npm: @toon-format/toon

Requirements

• Node.js 18+

• Your Spotify instance (self-hosted)

• Your Spotify public token (from Your Spotify settings)

Setup

1. Install Dependencies

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

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

Architecture

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

• Your Spotify - Self-hosted Spotify tracking dashboard (required)

• TOON Format - Token-efficient data format for LLMs

Documentation

• Usage Guide - Practical examples and workflows

• Tools Reference - Complete API reference for all 28 tools

• Architecture - System design documentation

• Configuration Examples - Ready-to-use configs for Claude, Gemini, etc.

Contributing

See CONTRIBUTING.md for guidelines.

Security

See SECURITY.md for vulnerability reporting.

License

Apache 2.0 - See LICENSE for details.