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?
| 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
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:
- 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
npm install
2. Build
npm run build
3. Get Your Spotify Token
- Open your Your Spotify dashboard
- Go to Settings
- 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 IDSPOTIFY_CLIENT_SECRET- Spotify App Client SecretSPOTIFY_ACCESS_TOKEN- Spotify OAuth Access TokenSPOTIFY_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
- 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.