# spotify-streamable-mcp-server
## 基本信息
- Slug: `iceener-spotify-streamable-mcp-server`
- Source: modelscope
- Publisher: @iceener/spotify-streamable-mcp-server
- Categories: cloud-platforms / audio-processing
- Hosted: No
- License: Unknown
- Source URL: https://www.modelscope.cn/mcp/servers/@iceener/spotify-streamable-mcp-server
## 简介
暂无描述。
## 安装提示

```bash
cd spotify-mcp bun install
```

## MCP Server 详情

# Spotify MCP Server

Streamable HTTP MCP server for Spotify  search music, control playback, manage playlists and saved songs.

Author: [overment](https://x.com/_overment)

> [!WARNING]
> This warning applies only to the HTTP transport and OAuth wrapper included for convenience. They are intended for personal/local use and are not productionhardened.
>
> The MCP tools and schemas themselves are implemented with strong validation, slim outputs, clear error handling, and other best practices.
>
> If you plan to deploy remotely, harden the OAuth/HTTP layer: proper token validation, secure storage, TLS termination, strict CORS/origin checks, rate limiting, audit logging, and compliance with Spotify's terms.

## Motivation

At first glance, a "Spotify MCP" may seem unnecessarypressing play or skipping a song is often faster by hand. It becomes genuinely useful when you don't know the exact title (e.g., "soundtrack from [movie title]"), when you want to "create and play a playlist that matches my mood", or when you're using voice. This MCP lets an LLM handle the fuzzy intent  search  selection  control loop, and it returns clear confirmations of what happened. It works well with voice interfaces and can be connected to agents/workflows for smarthome automations.

### Demo

![Alice App Demo](https://github.com/iceener/spotify-streamable-mcp-server/blob/main/_spec/heyalice-app.gif?raw=true)

*[Alice](https://heyalice.app)  a desktop AI assistant*

![Claude Desktop Demo](https://github.com/iceener/spotify-streamable-mcp-server/blob/main/_spec/claude-desktop.gif?raw=true)

*Claude Desktop*

## Features

-  **Search**  Find tracks, albums, artists, playlists
-  **Player Control**  Play, pause, skip, seek, volume, shuffle, repeat, queue
-  **Device Transfer**  Move playback between devices
-  **Playlists**  Create, edit, add/remove tracks, reorder
-  **Library**  Save/remove tracks, check if saved
-  **OAuth 2.1**  Secure PKCE flow with RS token mapping
-  **Dual Runtime**  Node.js/Bun or Cloudflare Workers
-  **Production Ready**  Encrypted token storage, rate limiting, multi-user support

### Design Principles

- **LLM-friendly**: Tools don't mirror Spotify's API 1:1  interfaces are simplified and unified
- **Batch-first**: Operations use arrays (`queries[]`, `operations[]`) to minimize tool calls
- **Clear feedback**: Every response includes human-readable `_msg` with what succeeded/failed
- **Best-effort verification**: Player control verifies device, context, and current track

## Quick Start

### 1. Install

```bash
cd spotify-mcp
bun install
```

### 2. Configure

```bash
cp .env.example .env
```

Edit `.env`:

```env
PORT=3000
AUTH_ENABLED=true

# From https://developer.spotify.com/dashboard
SPOTIFY_CLIENT_ID=your_client_id
SPOTIFY_CLIENT_SECRET=your_client_secret

# OAuth
OAUTH_SCOPES=playlist-read-private playlist-read-collaborative playlist-modify-public playlist-modify-private user-read-playback-state user-modify-playback-state user-read-currently-playing user-library-read user-library-modify
OAUTH_REDIRECT_URI=alice://oauth/callback
OAUTH_REDIRECT_ALLOWLIST=alice://oauth/callback
```

### 3. Configure Spotify Dashboard

Add redirect URIs in [Spotify Developer Dashboard](https://developer.spotify.com/dashboard):

```
http://127.0.0.1:3001/oauth/callback
alice://oauth/callback
```

### 4. Run

```bash
bun dev
# MCP: http://127.0.0.1:3000/mcp
# OAuth: http://127.0.0.1:3001
```

## Server Instructions (What the Model Sees)

```text
Use these tools to find music, get the current player status, control and transfer playback, and manage playlists and saved songs.

Tools
- search_catalog: Find songs, artists, albums, or playlists
- player_status: Read current player, available devices, queue, and current track
- spotify_control: Batch control playback (play, pause, next, previous, seek, volume, shuffle, repeat, transfer, queue)
- spotify_playlist: Manage playlists (list, get, items, create, update, add/remove items, reorder)
- spotify_library: Manage saved songs (get, add, remove, contains)

CRITICAL: device_id
- device_id is a long alphanumeric hash, NOT a human-readable name
- NEVER use the device name (like "MacBook Pro" or "iPhone") as device_id  this will fail!
- Always copy the exact device_id value from player_status  devices[].id or player.device_id
```

## Tools

### `search_catalog`

Search songs, artists, albums, and playlists.

**Input:**
```ts
{
  queries: string[];                              // Search terms
  types: ("album"|"artist"|"playlist"|"track")[]; // What to search
  market?: string;                                // 2-letter country code
  limit?: number;                                 // 1-50 (default 20)
  offset?: number;                                // 0-1000 (default 0)
  include_external?: "audio";
}
```

**Output:**
```ts
{
  _msg: string;
  batches: Array<{
    query: string;
    totals: Record<string, number>;
    items: Array<{ type, id, uri, name, artists?, album? }>;
  }>;
}
```

### `player_status`

Read current player state, devices, queue, and current track.

**Input:**
```ts
{ include?: ("player"|"devices"|"queue"|"current_track")[] }
```

**Output:**
```ts
{
  _msg: string;
  player?: {
    is_playing: boolean;
    device_id?: string;       // Use this for control!
    shuffle_state?: boolean;
    repeat_state?: "off"|"track"|"context";
    progress_ms?: number;
    context_uri?: string|null;
  };
  current_track?: { type, id, uri, name, artists, album, duration_ms } | null;
  devices?: Array<{
    id: string;               // Use this for control!
    name: string;
    type: string;
    is_active: boolean;
    volume_percent?: number;
  }>;
  queue?: { current_id?: string; next_ids: string[] };
}
```

### `spotify_control`

Control playback with batch operations.

**Input:**
```ts
{
  operations: Array<{
    action: "play"|"pause"|"next"|"previous"|"seek"|"volume"|"shuffle"|"repeat"|"transfer"|"queue";
    device_id?: string;       // Long alphan…