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.```bash
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```bash
npm install
2. Build```bash
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):```json
{
"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```bash
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)
- [x] Core analytics tools (Tier 1) - 5 tools
- [x] Enhanced analytics (Tier 2) - Custom Wrapped, Affinity, Rankings
- [x] Power analytics (Tier 3) - Patterns, Comparisons, Export
- [x] Account management (Tier 4) - Settings, Sharing
- [x] TOON format support for token-efficient output
- [x] Public token authentication
Optional (v0.2.x)
- [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.