Spotify MCP Server with Siri Integration

A Model Context Protocol (MCP) server that exposes Spotify functionality for seamless integration with Siri via Apple Shortcuts.

Features

Play Control: Play playlists, albums, and tracks
Search: Find music by song, artist, or album
Playback Control: Play, pause, skip, and adjust volume
Sleep Timer: Automatically pause playback after a specified duration
Siri Integration: HTTP bridge for Apple Shortcuts

Prerequisites

Node.js 18+
npm or yarn
Spotify Developer account
TypeScript 5.3+

Setup

1. Spotify Developer Setup

Go to Spotify Developer Dashboard
Create a new app
Note your Client ID and Client Secret
Add a redirect URI: http://localhost:3000/callback (or your preferred URI)

2. Project Setup

Clone or download this repository
Install dependencies:
```
npm install
```

Create a .env file in the root directory:

SPOTIFY_CLIENT_ID=your_client_id_here
SPOTIFY_CLIENT_SECRET=your_client_secret_here
SPOTIFY_REDIRECT_URI=http://localhost:3000/callback
HTTP_BRIDGE_PORT=3001
HTTP_BRIDGE_API_KEY=your_optional_api_key_here

Build the project:
```
npm run build
```

3. Authentication

Start the server:
```
npm start
```
The server will guide you through the OAuth flow if you're not authenticated
Visit the provided authorization URL
Authorize the app and copy the callback code
The tokens will be saved automatically in tokens.json

Usage

MCP Server

The MCP server runs on stdio and can be used with MCP-compatible clients:

npm start

HTTP Bridge (for Siri/Shortcuts)

The HTTP bridge exposes REST endpoints for Apple Shortcuts:

npm run bridge

API Endpoints

All endpoints support optional API key authentication via:

Header: Authorization: Bearer <api_key>
Query parameter: ?apiKey=<api_key>

Play Endpoints

POST /play/playlist

{
  "playlistName": "My Playlist",
  "deviceId": "optional_device_id"
}

POST /play/album

{
  "albumName": "Album Name",
  "artistName": "Artist Name",
  "deviceId": "optional_device_id"
}

POST /play/track

{
  "trackName": "Song Name",
  "artistName": "Artist Name",
  "deviceId": "optional_device_id"
}

Search

GET /search?q=query&limit=10

Returns search results for tracks, albums, and artists.

Playback Control

POST /control

{
  "action": "play|pause|skip-next|skip-previous|volume",
  "value": 50,
  "deviceId": "optional_device_id"
}

GET /now-playing

Returns information about the currently playing track.

Timer

POST /timer/set

{
  "durationMinutes": 30
}

POST /timer/cancel

{
  "timerId": "optional_timer_id"
}

GET /timer/list

Returns all active timers.

Health

GET /health

Check server status and authentication state.

Apple Shortcuts Integration

Setting Up Shortcuts

Open the Shortcuts app on your iPhone/iPad
Create a new shortcut
Add a "Get Contents of URL" action
Configure:
- Method: POST (or GET for search/now-playing)
- URL: http://your-server-ip:3001/play/playlist
- Headers:
  - Content-Type: application/json
  - Authorization: Bearer <your_api_key> (if using API key)
- Request Body: JSON with required parameters
Add a "Get Text from Input" action to parse the response
Add "Speak Text" action to have Siri confirm the action

Example Shortcut: Play Playlist

Create shortcut named "Play My Playlist"
Add input action to get playlist name from Siri
Add "Get Contents of URL":
- URL: http://your-server-ip:3001/play/playlist
- Method: POST
- Body: {"playlistName": "[Shortcut Input]"}
Add "Speak Text" to confirm

Example Voice Commands

"Hey Siri, play my workout playlist"
"Hey Siri, pause Spotify"
"Hey Siri, set a 30 minute sleep timer"
"Hey Siri, what's playing on Spotify?"
"Hey Siri, play [song name] by [artist]"

Running the Server for Shortcuts

For local network access:

Find your Mac's IP address: ifconfig | grep "inet "
Use that IP in Shortcuts: http://192.168.1.x:3001/...
Ensure your Mac's firewall allows connections on port 3001

For internet access, deploy the server to a cloud provider.

MCP Tools

The server exposes the following MCP tools:

play_playlist - Play a playlist by name
play_album - Play an album by name
play_track - Play a track by name
search_music - Search for music
control_playback - Control playback (play, pause, skip, volume)
get_current_playing - Get currently playing track
set_sleep_timer - Set a sleep timer
cancel_sleep_timer - Cancel active timers
get_active_timers - List active timers

Development

# Development mode with auto-reload
npm run dev

# Build TypeScript
npm run build

# Run MCP server
npm start

# Run HTTP bridge
npm run bridge

Project Structure

src/
  server.ts              # MCP server entry point
  http-bridge.ts         # HTTP server for Shortcuts
  spotify/
    auth.ts             # OAuth authentication
    client.ts           # Spotify API client
  tools/
    play.ts             # Play operations
    search.ts           # Search operations
    playback.ts         # Playback control
    timer.ts            # Timer operations
  timer.ts              # Timer manager
  types.ts              # Type definitions

Troubleshooting

Authentication Issues

Ensure your redirect URI matches exactly in Spotify Dashboard
Check that tokens.json is created and contains valid tokens
Re-authenticate by deleting tokens.json and restarting

Device Not Found

Make sure a Spotify device is active (app open and playing)
Use the device selection in the Spotify app
Check device availability via Spotify API

Connection Issues

Verify the HTTP bridge port (default: 3001) is not blocked
Check firewall settings
Ensure the server is accessible on your network

License

MIT