kriss/mcp-spotify
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
2ae10daef55064326181d555795443b189a99f49
mcp-spotify/docs/superpowers/plans/2026-05-22-spotify-mcp.md
Christophe Vila 2ae10daef5 added missing files
2026-05-25 21:34:23 +02:00

582 lines
17 KiB
Markdown
Raw Blame History

# Spotify MCP Server Implementation Plan
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** Build a Python MCP server exposing Spotify library and playlist management as 6 tools for Claude via stdio transport.
**Architecture:** Two source files — `spotify_client.py` wraps spotipy (auth + all API calls, including pagination and data shaping), `server.py` handles MCP tool registration and routing. The `mcp` SDK handles stdio; `spotipy` handles OAuth PKCE flow and token caching. Token is cached relative to the script file so Claude Code always finds it regardless of working directory.
**Tech Stack:** Python 3.11+, `mcp` (MCP Python SDK), `spotipy` (Spotify Web API + OAuth), `python-dotenv`
---
### Task 1: Initialize project
**Files:**
- Create: `pyproject.toml`
- Create: `.env.example`
- Create: `.gitignore`
- [ ] **Step 1: Initialize git repository**
```bash
cd /Users/kriss/Dev/scm/scm.vilanet.fr/kriss/mcp-spotify
git init
```
Expected: `Initialized empty Git repository in .../mcp-spotify/.git/`
- [ ] **Step 2: Create pyproject.toml**
```toml
[project]
name = "mcp-spotify"
version = "0.1.0"
requires-python = ">=3.11"
dependencies = [
"mcp>=1.0.0",
"spotipy>=2.24.0",
"python-dotenv>=1.0.0",
]
[build-system]
requires = ["setuptools>=68"]
build-backend = "setuptools.build_meta"
[tool.setuptools]
py-modules = ["server", "spotify_client"]
```
- [ ] **Step 3: Create .env.example**
```
SPOTIPY_CLIENT_ID=your_client_id_here
SPOTIPY_CLIENT_SECRET=your_client_secret_here
SPOTIPY_REDIRECT_URI=http://localhost:8888/callback
```
- [ ] **Step 4: Create .gitignore**
```
.env
.venv/
__pycache__/
*.pyc
.cache
*.egg-info/
dist/
```
- [ ] **Step 5: Create virtual environment and install dependencies**
```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
```
Expected: Dependencies install without errors (`mcp`, `spotipy`, `python-dotenv` all present).
Verify with: `pip show mcp spotipy python-dotenv` — all three should display version info.
- [ ] **Step 6: Commit**
```bash
git add pyproject.toml .env.example .gitignore
git commit -m "chore: initialize project scaffold"
```
---
### Task 2: Implement Spotify client
**Files:**
- Create: `spotify_client.py`
- [ ] **Step 1: Create spotify_client.py**
```python
import os
import pathlib
from dotenv import load_dotenv
import spotipy
from spotipy.oauth2 import SpotifyOAuth
from spotipy.cache_handler import CacheFileHandler
load_dotenv()
_SCOPES = " ".join([
"playlist-read-private",
"playlist-read-collaborative",
"playlist-modify-public",
"playlist-modify-private",
"user-library-read",
])
# Cache relative to this file so Claude Code always finds it regardless of cwd
_CACHE_PATH = pathlib.Path(__file__).parent / ".cache"
_client: spotipy.Spotify | None = None
def get_client() -> spotipy.Spotify:
global _client
if _client is None:
client_id = os.environ.get("SPOTIPY_CLIENT_ID")
client_secret = os.environ.get("SPOTIPY_CLIENT_SECRET")
redirect_uri = os.environ.get("SPOTIPY_REDIRECT_URI", "http://localhost:8888/callback")
if not client_id or not client_secret:
raise RuntimeError(
"Missing SPOTIPY_CLIENT_ID or SPOTIPY_CLIENT_SECRET. "
"Copy .env.example to .env and fill in your Spotify app credentials."
)
_client = spotipy.Spotify(
auth_manager=SpotifyOAuth(
client_id=client_id,
client_secret=client_secret,
redirect_uri=redirect_uri,
scope=_SCOPES,
cache_handler=CacheFileHandler(cache_path=str(_CACHE_PATH)),
)
)
return _client
def _format_duration(ms: int) -> str:
seconds = ms // 1000
minutes, seconds = divmod(seconds, 60)
return f"{minutes}:{seconds:02d}"
def list_playlists() -> list[dict]:
sp = get_client()
results = []
response = sp.current_user_playlists(limit=50)
while response:
for item in response["items"]:
results.append({
"id": item["id"],
"name": item["name"],
"description": item.get("description", ""),
"tracks_total": item["tracks"]["total"],
"public": item["public"],
"uri": item["uri"],
})
response = sp.next(response) if response["next"] else None
return results
def get_playlist_tracks(playlist_id: str) -> list[dict]:
sp = get_client()
results = []
response = sp.playlist_items(playlist_id, additional_types=["track"])
while response:
for item in response["items"]:
track = item.get("track")
if not track or track.get("type") != "track":
continue
results.append({
"name": track["name"],
"artists": [a["name"] for a in track["artists"]],
"album": track["album"]["name"],
"duration_ms": track["duration_ms"],
"duration": _format_duration(track["duration_ms"]),
"popularity": track["popularity"],
"uri": track["uri"],
"added_at": item["added_at"],
})
response = sp.next(response) if response["next"] else None
return results
def list_saved_tracks(limit: int = 50) -> list[dict]:
sp = get_client()
results = []
response = sp.current_user_saved_tracks(limit=min(limit, 50))
while response and len(results) < limit:
for item in response["items"]:
if len(results) >= limit:
break
track = item["track"]
results.append({
"name": track["name"],
"artists": [a["name"] for a in track["artists"]],
"album": track["album"]["name"],
"duration_ms": track["duration_ms"],
"duration": _format_duration(track["duration_ms"]),
"popularity": track["popularity"],
"uri": track["uri"],
"added_at": item["added_at"],
})
if response["next"] and len(results) < limit:
response = sp.next(response)
else:
break
return results
def search_tracks(query: str, limit: int = 10) -> list[dict]:
sp = get_client()
response = sp.search(q=query, type="track", limit=min(limit, 50))
results = []
for track in response["tracks"]["items"]:
results.append({
"name": track["name"],
"artists": [a["name"] for a in track["artists"]],
"album": track["album"]["name"],
"duration_ms": track["duration_ms"],
"duration": _format_duration(track["duration_ms"]),
"popularity": track["popularity"],
"uri": track["uri"],
})
return results
def create_playlist(name: str, description: str = "", public: bool = False) -> dict:
sp = get_client()
user_id = sp.current_user()["id"]
playlist = sp.user_playlist_create(
user=user_id,
name=name,
public=public,
description=description,
)
return {
"id": playlist["id"],
"name": playlist["name"],
"uri": playlist["uri"],
"public": playlist["public"],
}
def add_tracks_to_playlist(playlist_id: str, track_uris: list[str]) -> dict:
sp = get_client()
for i in range(0, len(track_uris), 100):
sp.playlist_add_items(playlist_id, track_uris[i : i + 100])
return {"added": len(track_uris)}
```
- [ ] **Step 2: Verify the module imports without errors**
```bash
source .venv/bin/activate
python -c "import spotify_client; print('OK')"
```
Expected: `OK` — no import errors (`.env` is not required at import time, only when `get_client()` is called).
- [ ] **Step 3: Commit**
```bash
git add spotify_client.py
git commit -m "feat: implement Spotify client module"
```
---
### Task 3: Implement MCP server
**Files:**
- Create: `server.py`
- [ ] **Step 1: Create server.py**
```python
import asyncio
import json
import sys
from mcp.server import Server
from mcp.server.stdio import stdio_server
from mcp.types import Tool, TextContent
import spotify_client
server = Server("spotify-mcp")
@server.list_tools()
async def handle_list_tools() -> list[Tool]:
return [
Tool(
name="list_playlists",
description="List the authenticated user's Spotify playlists.",
inputSchema={"type": "object", "properties": {}, "required": []},
),
Tool(
name="get_playlist_tracks",
description=(
"Get all tracks in a Spotify playlist with full metadata: "
"name, artists, album, duration_ms, duration (mm:ss), popularity, URI, added_at."
),
inputSchema={
"type": "object",
"properties": {
"playlist_id": {
"type": "string",
"description": "Spotify playlist ID (from list_playlists)",
},
},
"required": ["playlist_id"],
},
),
Tool(
name="list_saved_tracks",
description="Get the user's liked/saved tracks from Spotify.",
inputSchema={
"type": "object",
"properties": {
"limit": {
"type": "integer",
"description": "Maximum number of tracks to return (default 50)",
},
},
"required": [],
},
),
Tool(
name="search_tracks",
description=(
"Search Spotify for tracks. "
"Returns track URIs that can be passed to add_tracks_to_playlist."
),
inputSchema={
"type": "object",
"properties": {
"query": {"type": "string", "description": "Search query"},
"limit": {
"type": "integer",
"description": "Maximum results to return (default 10, max 50)",
},
},
"required": ["query"],
},
),
Tool(
name="create_playlist",
description="Create a new Spotify playlist for the authenticated user.",
inputSchema={
"type": "object",
"properties": {
"name": {"type": "string", "description": "Playlist name"},
"description": {
"type": "string",
"description": "Playlist description (optional)",
},
"public": {
"type": "boolean",
"description": "Whether the playlist is public (default false)",
},
},
"required": ["name"],
},
),
Tool(
name="add_tracks_to_playlist",
description="Add tracks to a Spotify playlist by their URIs (e.g. spotify:track:...).",
inputSchema={
"type": "object",
"properties": {
"playlist_id": {
"type": "string",
"description": "Spotify playlist ID",
},
"track_uris": {
"type": "array",
"items": {"type": "string"},
"description": "List of Spotify track URIs",
},
},
"required": ["playlist_id", "track_uris"],
},
),
]
@server.call_tool()
async def handle_call_tool(name: str, arguments: dict | None) -> list[TextContent]:
arguments = arguments or {}
try:
if name == "list_playlists":
result = await asyncio.to_thread(spotify_client.list_playlists)
elif name == "get_playlist_tracks":
result = await asyncio.to_thread(
spotify_client.get_playlist_tracks, arguments["playlist_id"]
)
elif name == "list_saved_tracks":
result = await asyncio.to_thread(
spotify_client.list_saved_tracks, arguments.get("limit", 50)
)
elif name == "search_tracks":
result = await asyncio.to_thread(
spotify_client.search_tracks,
arguments["query"],
arguments.get("limit", 10),
)
elif name == "create_playlist":
result = await asyncio.to_thread(
spotify_client.create_playlist,
arguments["name"],
arguments.get("description", ""),
arguments.get("public", False),
)
elif name == "add_tracks_to_playlist":
result = await asyncio.to_thread(
spotify_client.add_tracks_to_playlist,
arguments["playlist_id"],
arguments["track_uris"],
)
else:
raise ValueError(f"Unknown tool: {name}")
except Exception as e:
return [TextContent(type="text", text=f"Error: {e}")]
return [TextContent(type="text", text=json.dumps(result, ensure_ascii=False, indent=2))]
async def _run_server() -> None:
async with stdio_server() as (read_stream, write_stream):
await server.run(
read_stream,
write_stream,
server.create_initialization_options(),
)
if __name__ == "__main__":
if "--auth" in sys.argv:
print("Authenticating with Spotify (a browser window will open)...")
spotify_client.get_client()
print("Authentication successful! Token cached.")
sys.exit(0)
try:
spotify_client.get_client()
except RuntimeError as e:
print(f"Startup error: {e}", file=sys.stderr)
sys.exit(1)
asyncio.run(_run_server())
```
- [ ] **Step 2: Verify server.py imports and syntax are clean**
```bash
source .venv/bin/activate
python -c "import server; print('OK')"
```
Expected: `OK`
- [ ] **Step 3: Commit**
```bash
git add server.py
git commit -m "feat: implement MCP server with 6 Spotify tools"
```
---
### Task 4: First auth run, README, and Claude Code registration
**Files:**
- Create: `README.md`
- [ ] **Step 1: Copy .env.example to .env and fill in credentials**
Go to https://developer.spotify.com/dashboard, create an app, add `http://localhost:8888/callback` as a Redirect URI, then:
```bash
cp .env.example .env
# Open .env in an editor and fill in SPOTIPY_CLIENT_ID and SPOTIPY_CLIENT_SECRET
```
- [ ] **Step 2: Run the one-time auth flow**
```bash
source .venv/bin/activate
python server.py --auth
```
Expected: Browser opens Spotify login → after authorizing, terminal prints:
```
Authentication successful! Token cached.
```
The token is saved to `.cache` in the project directory. All subsequent runs (including when launched by Claude Code) load it silently without opening a browser.
- [ ] **Step 3: Create README.md**
````markdown
# mcp-spotify
A Python MCP server that exposes Spotify library and playlist management as tools for Claude.
## Prerequisites
- Python 3.11+
- A Spotify Developer app — [create one here](https://developer.spotify.com/dashboard)
- In the app settings, add `http://localhost:8888/callback` as a Redirect URI
## Setup
**1. Install dependencies**
```bash
python3 -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -e .
```
**2. Configure credentials**
```bash
cp .env.example .env
# Edit .env: fill in SPOTIPY_CLIENT_ID and SPOTIPY_CLIENT_SECRET
```
**3. Authenticate with Spotify (once)**
```bash
source .venv/bin/activate
python server.py --auth
```
A browser window opens. Log in and authorize the app. The token is cached to `.cache` in the project directory — subsequent runs (including from Claude Code) use it silently.
**4. Register with Claude Code**
Add to `~/.claude/settings.json` (or your project's `.claude/settings.json`):
```json
{
"mcpServers": {
"spotify": {
"command": "/absolute/path/to/mcp-spotify/.venv/bin/python",
"args": ["/absolute/path/to/mcp-spotify/server.py"]
}
}
}
```
Replace `/absolute/path/to/mcp-spotify` with the actual path on your system. Run `pwd` in the project directory to get it.
## Available Tools
| Tool | Description |
|---|---|
| `list_playlists` | List your Spotify playlists |
| `get_playlist_tracks` | All tracks in a playlist — name, artists, album, duration, URI, added date |
| `list_saved_tracks` | Your liked/saved tracks |
| `search_tracks` | Search Spotify for tracks by query |
| `create_playlist` | Create a new playlist |
| `add_tracks_to_playlist` | Add tracks to a playlist by URI |
````
- [ ] **Step 4: Commit**
```bash
git add README.md
git commit -m "docs: add README with setup and Claude Code registration instructions"
```
Reference in New Issue View Git Blame Copy Permalink