Spotify MCP Server

A comprehensive Model Context Protocol (MCP) server for Spotify

Provides 51 granular tools perfect for building dynamic HUDs, music visualizers, and AI-powered music control interfaces

Why This MCP Server?

This MCP server is specifically designed for dynamic HUD applications where you need individual data points. Instead of parsing large JSON responses, each tool returns exactly what you need.

Use Case	Traditional Approach	This Server
Get track name	Parse JSON → Extract `item.name`	`spotify_get_track_name` → Direct value
Get artist	Parse JSON → Extract `item.artists[0].name`	`spotify_get_artist_name` → Direct value
Show countdown timer	Parse JSON → Calculate remaining time → Format	`spotify_get_time_remaining_formatted` → "3:24"
Progress bar	Parse JSON → Calculate percentage	`spotify_get_track_progress_percentage` → "67"
Play/pause button	Parse JSON → Check `is_playing`	`spotify_is_playing` → "true" or "false"

Complete Tool Coverage

51 tools organized into 9 categories for maximum flexibility

Category	Tool Count	Description
Bulk State Tools	2	Get complete playback state or track info in one call
Granular Track Info	16	Individual tools for artist, track name, album, duration, progress, artwork, and more
Granular Device Info	6	Get device name, type, volume, ID, and active status individually
Granular Playback State	5	Individual tools for play state, shuffle, repeat mode, and context
Playback Control	7	Play, pause, next, previous, seek, shuffle, and repeat controls
Volume & Device Control	2	Set volume and transfer playback between devices
Queue Management	3	View queue, add tracks, and see recently played
Search & Discovery	5	Search tracks, albums, artists, and get detailed information
Library Management	5	Manage saved tracks and playlists

Key Features

Feature	Description
Granular Data Access	51 specialized tools for precise data retrieval
HUD Optimized	Returns plain text values perfect for UI components
Production Ready	Comprehensive error handling and automatic token refresh
Full Test Coverage	94 tests covering all 51 tools and edge cases
Type Safe	Built with TypeScript and Zod schema validation
OAuth Authentication	Automatic token management and refresh
Zero Dependencies	Only requires Node.js 18+ and Spotify account

Installation

Step	Instructions
1. Prerequisites	• Node.js 18+ installed • Spotify Account (Premium recommended) • Spotify Developer App credentials
2. Get Credentials	1. Go to Spotify Developer Dashboard 2. Create a new app 3. Note your Client ID and Client Secret 4. Add `http://localhost:8888/callback` to Redirect URIs
3. Install	`npm install`
4. Configure	Copy example env: `cp .env.example .env` Edit `.env` with credentials: `SPOTIFY_CLIENT_ID=your_id` `SPOTIFY_CLIENT_SECRET=your_secret` `SPOTIFY_REDIRECT_URI=http://localhost:8888/callback`
5. Authenticate	`npm run auth` (Opens browser to log in and saves tokens)
6. Build	`npm run build`
7. Configure Client	Add to `claude_desktop_config.json`: { "mcpServers": { "spotify": { "command": "node", "args": ["/PATH/TO/dist/index.js"], "env": { ... } } } }

Usage

Once configured, restart your MCP client and you'll have access to all 51 tools!

Example Queries

Category	User Query	Tool Used
Dynamic HUDs	"What's the current track name?"	`spotify_get_track_name`
	"Get the artist"	`spotify_get_artist_name`
	"What's the time remaining?"	`spotify_get_time_remaining_formatted`
	"What's the playback progress percentage?"	`spotify_get_track_progress_percentage`
	"Is music playing?"	`spotify_is_playing`
Playback Control	"Pause the music"	`spotify_pause`
	"Skip to the next song"	`spotify_next`
	"Set volume to 50%"	`spotify_set_volume`
	"Enable shuffle"	`spotify_set_shuffle`
Discovery	"Search for tracks by The Beatles"	`spotify_search`
	"Add this song to my library"	`spotify_save_track`

Complete API Reference

Bulk State Tools (2)

Tool	Returns	Use Case
`spotify_get_playback_state`	Complete playback state (JSON)	Get all playback info at once
`spotify_get_current_track`	Complete track info (JSON)	Get all track info at once

Granular Track Info Tools (16)

Tool	Returns	Perfect For
`spotify_get_track_name`	Track name only	HUD track display
`spotify_get_artist_name`	Primary artist name	HUD artist display
`spotify_get_all_artists`	All artists (comma-separated)	Full artist credits
`spotify_get_album_name`	Album name only	HUD album display
`spotify_get_track_duration_ms`	Duration in milliseconds	Calculations
`spotify_get_track_duration_formatted`	Duration as "M:SS"	HUD duration display
`spotify_get_track_progress_ms`	Current position in ms	Calculations
`spotify_get_track_progress_formatted`	Current position as "M:SS"	HUD position display
`spotify_get_time_remaining_ms`	Time left in ms	Calculations
`spotify_get_time_remaining_formatted`	Time left as "M:SS"	HUD countdown timer
`spotify_get_track_progress_percentage`	Progress as 0-100	Progress bars
`spotify_get_track_uri`	Spotify URI	Playback control
`spotify_get_track_id`	Spotify ID	API calls
`spotify_get_album_art_url`	Album artwork URL	HUD artwork display
`spotify_get_track_explicit`	"true" or "false"	Explicit content indicator
`spotify_get_track_popularity`	Popularity 0-100	Track metrics

Granular Device Tools (6)

Tool	Returns	Perfect For
`spotify_get_device_name`	Device name	HUD device display
`spotify_get_device_type`	Device type	Device icons
`spotify_get_device_volume`	Volume 0-100	Volume displays
`spotify_get_device_id`	Device ID	Device switching
`spotify_is_device_active`	"true" or "false"	Active device indicator
`spotify_get_available_devices`	All devices (JSON)	Device selection

Granular Playback State Tools (5)

Tool	Returns	Perfect For
`spotify_is_playing`	"true" or "false"	Play/pause button states
`spotify_get_shuffle_state`	"true" or "false"	Shuffle button states
`spotify_get_repeat_mode`	"off", "track", or "context"	Repeat button states
`spotify_get_context_type`	Context type	Playlist/album indicators
`spotify_get_context_uri`	Context URI	Context switching

Playback Control Tools (7)

Tool	Parameters	Description
`spotify_play`	device_id?, context_uri?, uris?, position_ms?	Start/resume playback
`spotify_pause`	device_id?	Pause playback
`spotify_next`	device_id?	Skip to next track
`spotify_previous`	device_id?	Skip to previous track
`spotify_seek`	position_ms, device_id?	Seek to position
`spotify_set_shuffle`	state (bool), device_id?	Toggle shuffle
`spotify_set_repeat`	state (track/context/off), device_id?	Set repeat mode

Volume & Device Control Tools (2)

Tool	Parameters	Description
`spotify_set_volume`	volume_percent (0-100), device_id?	Set playback volume
`spotify_transfer_playback`	device_id, play?	Transfer playback to device

Queue Management Tools (3)

Tool	Parameters	Description
`spotify_get_queue`	-	Get current playback queue
`spotify_add_to_queue`	uri, device_id?	Add track to queue
`spotify_get_recently_played`	limit?	Get recently played tracks

Search & Discovery Tools (5)

Tool	Parameters	Description
`spotify_search`	query, type[], limit?	Search for tracks/albums/artists/playlists
`spotify_get_track_info`	track_id	Get detailed track information
`spotify_get_album_info`	album_id	Get detailed album information
`spotify_get_artist_info`	artist_id	Get detailed artist information
`spotify_get_artist_top_tracks`	artist_id, market?	Get artist's top tracks

Library Management Tools (5)

Tool	Parameters	Description
`spotify_get_saved_tracks`	limit?, offset?	Get user's saved tracks
`spotify_save_track`	track_id	Save (like) a track
`spotify_remove_saved_track`	track_id	Remove (unlike) a track
`spotify_get_playlists`	limit?, offset?	Get user's playlists
`spotify_get_playlist`	playlist_id	Get playlist details

Architecture

spotify-mcp-server/
├── src/
│   ├── auth/
│   │   ├── setup.ts              # OAuth authentication flow
│   │   └── token-manager.ts      # Token storage and refresh
│   ├── tools/
│   │   └── spotify-api.ts        # Spotify API wrapper
│   └── index.ts                  # Main MCP server with all 51 tools
├── tests/                        # Comprehensive test suite (94 tests)
├── dist/                         # Compiled JavaScript (generated)
├── package.json
├── tsconfig.json
├── eslint.config.mjs
└── .env                          # Your credentials (not committed)

Token Management

Token Details
Tokens are stored in `spotify-tokens.json` (automatically created)
Access tokens are automatically refreshed when they expire
You only need to run `npm run auth` once (or if tokens are revoked)
Tokens persist across server restarts

Error Handling

The server provides clear, actionable error messages:

Error Code	Meaning
401 Unauthorized	Re-run `npm run auth`
403 Forbidden	Feature may require Spotify Premium
404 Not Found	No active device or track
429 Rate Limit	Too many requests, wait a moment

Development

Task	Command
Run Tests	`npm test` (all) `npm run test:watch` (watch mode) `npm run test:coverage` (report)
Run Linter	`npm run lint`
Clean Build	`npm run clean && npm run build`
Debugging	Server logs to stderr

Use Cases

Dynamic HUD Applications

Perfect for creating real-time music displays:

// Get individual values for your HUD components
const trackName = await callTool("spotify_get_track_name");
const artist = await callTool("spotify_get_artist_name");
const progress = await callTool("spotify_get_track_progress_percentage");
const timeRemaining = await callTool("spotify_get_time_remaining_formatted");
const isPlaying = await callTool("spotify_is_playing");
const albumArt = await callTool("spotify_get_album_art_url");

Music Visualizers

Get precise timing and state info:

const progressMs = await callTool("spotify_get_track_progress_ms");
const durationMs = await callTool("spotify_get_track_duration_ms");
const isPlaying = await callTool("spotify_is_playing");

AI Music Assistants

Natural language control:

User: "What's playing?"
AI: Uses spotify_get_track_name and spotify_get_artist_name

User: "How much time is left?"
AI: Uses spotify_get_time_remaining_formatted

User: "Skip this song"
AI: Uses spotify_next