Playlist MCP Agent

Create, manage, and optimize Spotify playlists through natural language using AI and MCP.

Prerequisites

1. Python 3.12+

2. Spotify Developer app

   • Create an app at https://developer.spotify.com/dashboard

   • Copy the Client ID and Client Secret

   • Add redirect URI: http://127.0.0.1:8888/callback

   • Add your Spotify account under User Management (required for write operations in Development Mode)

Related MCP server: spotify-mcp

Setup

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev,llm]"

cp .env.example .env
# Edit .env with your Spotify credentials

Authenticate with Spotify

Run once to save a refresh token locally:

python authenticate.py

Tokens are stored at:

~/.playlist_agent/tokens.json

Run the MCP Server

Streamable HTTP (Recommended)

python server.py --http

Server URL:

http://127.0.0.1:8080/mcp

Stdio Mode (Claude Desktop)

python server.py --stdio

Connect to Claude Desktop

Edit:

~/Library/Application Support/Claude/claude_desktop_config.json

Add:

{
  "mcpServers": {
    "playlistAgent": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": [
        "/absolute/path/to/server.py",
        "--stdio"
      ]
    }
  }
}

Example:

{
  "mcpServers": {
    "playlistAgent": {
      "command": "/Users/amankumar/Documents/projects/playlistAgent/.venv/bin/python",
      "args": [
        "/Users/amankumar/Documents/projects/playlistAgent/server.py",
        "--stdio"
      ]
    }
  }
}

Restart Claude Desktop after updating the configuration.

Verify Claude Connection

Check logs:

~/Library/Logs/Claude/

Successful startup should show:

Server started and connected successfully

Connect to Cursor

Add an MCP server with:

• Type: MCP (Streamable HTTP)

• URL: http://127.0.0.1:8080/mcp

Example Cursor config:

{
  "mcpServers": {
    "playlist-agent": {
      "url": "http://127.0.0.1:8080/mcp"
    }
  }
}

MCP Tools

Smoke Test (Phase 1)

After authenticating:

python smoke_test.py

Tests

pytest

Integration tests:

RUN_INTEGRATION=1 pytest -m integration

Requires a valid Spotify authentication setup.

Environment Variables

See .env.example for all supported options.

LLM generation (Phase 3+) requires:

LLM_PROVIDER=openai

or

LLM_PROVIDER=anthropic

and the corresponding API key.

Architecture

Claude / Cursor / ChatGPT
            │
            ▼
      PlaylistAgent MCP
            │
    ┌───────┼────────┐
    ▼       ▼        ▼
 Spotify   LLM    Recommendation
   API    Provider    Engine

Roadmap

Phase 1

• Spotify OAuth

• Search tracks

• Create playlists

• Add tracks

Phase 2

• MCP integration

• Claude Desktop support

• Cursor support

Phase 3

• AI playlist generation

• Mood and genre understanding

Phase 4

• Playlist editing

• Playlist optimization

• Recommendation engine

Phase 5

• Taste profile engine

• Personalized playlist memory

• Advanced music discovery