Playlistable MCP

Playlistable MCP

Create AI-powered Spotify playlists and discover music using the Playlistable MCP server.

Authentication

Needs a Playlistable API key (PLAYLISTABLE_API_KEY env var or config/auth.json).

To get one:

node {baseDir}/scripts/auth.mjs

Fully automatic — starts a local HTTP server, opens browser for Spotify OAuth, catches the redirect, exchanges the code for an API key via PKCE, and saves it to {baseDir}/config/auth.json. No manual copy-paste needed.

If the key is already saved, scripts read it automatically from config/auth.json.

How it works

The MCP server at https://mcp.playlistable.io exposes tools via Streamable HTTP transport. The mcp-call.mjs script sends JSON-RPC requests directly — no MCP SDK needed.

Common workflows

Generate a playlist: User describes a mood → generate_playlist creates an async Spotify playlist → returns playlist URL immediately. Tracks appear in the background.

Browse playlists: get_playlists lists all user playlists. get_playlist gets details + tracks for a specific one.

Edit a playlist: edit_playlist adds or removes songs by Spotify track ID.

Search music: search_songs and search_artists search Spotify directly.

Get suggestions: playlist_suggestions returns 6 AI-generated mood suggestions based on the user's listening history and time of day.

Scripts

Authenticate

node {baseDir}/scripts/auth.mjs

Call MCP tools

node {baseDir}/scripts/mcp-call.mjs <tool> [json-params]
node {baseDir}/scripts/mcp-call.mjs --list-tools

Examples:

# Generate a playlist
node {baseDir}/scripts/mcp-call.mjs generate_playlist '{"mood": "chill lo-fi for studying"}'

# Get personalized suggestions
node {baseDir}/scripts/mcp-call.mjs playlist_suggestions '{"userHour": 22}'

# List playlists
node {baseDir}/scripts/mcp-call.mjs get_playlists

# Get playlist details
node {baseDir}/scripts/mcp-call.mjs get_playlist '{"id": "PLAYLIST_ID"}'

# Edit playlist songs
node {baseDir}/scripts/mcp-call.mjs edit_playlist '{"id": "PLAYLIST_ID", "addedSongs": ["4iV5W9uYEdYUVa79Axb7Rh"], "removedSongs": []}'

# Delete playlist
node {baseDir}/scripts/mcp-call.mjs delete_playlist '{"id": "PLAYLIST_ID"}'

# Search songs
node {baseDir}/scripts/mcp-call.mjs search_songs '{"query": "Blinding Lights", "limit": 5}'

# Search artists
node {baseDir}/scripts/mcp-call.mjs search_artists '{"query": "The Weeknd", "limit": 5}'

# List all available tools
node {baseDir}/scripts/mcp-call.mjs --list-tools

Available MCP Tools

See references/api_reference.md for full parameter details, response formats, and error handling.

Playlist Generation Flow (important)

Playlist generation takes ~30 seconds. Always follow this flow:

1. Call generate_playlist → returns immediately with id and Spotify URL
2. Share the Spotify URL with the user right away so they have it
3. Wait ~15s, then poll get_playlist every 10 seconds until status === "ready"
4. Once ready, display the track list to the user

Use the --wait flag to handle this automatically:

node {baseDir}/scripts/mcp-call.mjs generate_playlist '{"mood": "..."}' --wait

This generates, polls until ready (~30s), then prints the full playlist with tracks.

Notes

• Free users get a limited "teaser" playlist. Paid users get full playlists.
• playlist_suggestions is time-aware — pass userHour for better results (morning workout vs late-night chill).
• Songs are identified by Spotify track IDs (e.g., 4iV5W9uYEdYUVa79Axb7Rh). Use search_songs to find IDs.