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:

```bash
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

```bash
node {baseDir}/scripts/auth.mjs
```

### Call MCP tools

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

**Examples:**

```bash
# 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": "P...