Metadata-Version: 2.5
Name: spotify-soundtrack-mcp
Version: 1.0.0
Summary: Spotify & TMDB FastMCP server with 115 tools — filmography playlists, smart curation, playback control, and a built-in Soundtrack Studio web UI.
Project-URL: Homepage, https://github.com/Chiru144/Spotify-MCP-Web-MCP-Server
Project-URL: Repository, https://github.com/Chiru144/Spotify-MCP-Web-MCP-Server
Project-URL: Bug Tracker, https://github.com/Chiru144/Spotify-MCP-Web-MCP-Server/issues
Author: Chiru144
License: MIT License
        
        Copyright (c) 2024 Chiru144
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE.md
Keywords: agent,ai,claude,cursor,fastmcp,mcp,playlist,spotify,tmdb
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
Classifier: Topic :: Multimedia :: Sound/Audio
Requires-Python: >=3.10
Requires-Dist: beautifulsoup4>=4.13.0
Requires-Dist: ddgs>=9.0.0
Requires-Dist: fastapi>=0.115.0
Requires-Dist: fastmcp>=4.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: requests>=2.32.0
Requires-Dist: spotipy>=2.26.0
Requires-Dist: uvicorn>=0.30.0
Provides-Extra: all
Requires-Dist: spotify-mcp-web>=1.0.0; extra == 'all'
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Provides-Extra: web
Requires-Dist: spotify-mcp-web>=1.0.0; extra == 'web'
Description-Content-Type: text/markdown

# spotify-soundtrack-mcp

[![PyPI](https://img.shields.io/pypi/v/spotify-soundtrack-mcp)](https://pypi.org/project/spotify-soundtrack-mcp/)
[![Python](https://img.shields.io/pypi/pyversions/spotify-soundtrack-mcp)](https://pypi.org/project/spotify-soundtrack-mcp/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE.md)

> **115 FastMCP Tools** for Spotify & TMDB — filmography playlists, smart playlist curation, a local library cache, vibe/radio/era/time-capsule playlist generators, taste analytics, Spotify Connect hardware control, and a built-in **Soundtrack Curator & Staging Studio** web UI.

---

## Installation

```bash
pip install spotify-soundtrack-mcp
```

---

## Quick Start

### 1. Configure credentials

Create a `.env` file in your working directory:

```env
# Spotify Developer App credentials (PKCE — no secret needed!)
# Get yours at https://developer.spotify.com/dashboard
SPOTIPY_CLIENT_ID=your_spotify_client_id_here
SPOTIPY_REDIRECT_URI=http://127.0.0.1:8888/callback

# TMDB (optional, enables cinema/filmography features)
# Get from https://www.themoviedb.org/settings/api
TMDB_API_KEY=your_tmdb_api_key_here
# OR: TMDB_READ_ACCESS_TOKEN=your_tmdb_read_access_token_here
```

> **Important:** In your Spotify Developer Dashboard, add `http://127.0.0.1:8888/callback` as a Redirect URI.

### 2. Authenticate

```bash
spotify-mcp-auth
```

This opens your browser for Spotify login and saves the token locally.

### 3. Run

**For Claude Desktop / Cursor (stdio transport):**
```bash
spotify-mcp
# With a specific toolset (recommended for token efficiency):
spotify-mcp --toolsets=core
```

**For web/remote SSE transport:**
```bash
spotify-soundtrack-mcp
# Custom host/port via env:
HOST=0.0.0.0 PORT=8080 spotify-soundtrack-mcp
```

---

## Claude Desktop Configuration

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "spotify": {
      "command": "spotify-mcp",
      "args": ["--toolsets=core"],
      "env": {
        "SPOTIPY_CLIENT_ID": "your_client_id",
        "TMDB_API_KEY": "your_tmdb_key"
      }
    }
  }
}
```

---

## Toolsets

| Toolset | Tools | Best For |
|---|---|---|
| `core` *(default)* | 16 | Filmography curation, movie soundtracks, search, dedup |
| `playback` | 31 | DJ controls, device switching, queue management |
| `playlists` | 37 | Advanced playlist diff, merging, splitting, vibe/radio/era/time-capsule generators |
| `search` | 16 | Music discovery, mood/genre search, TMDB lookup |
| `taste` | 14 | Top tracks, listening patterns, taste profile |
| `library` | 11 | Saved tracks, albums, local library cache (sync, stats, query) |
| `browse` | 5 | Artist, album, track, your profile lookup |
| `all` | 115 | Full access to every tool |

```bash
spotify-mcp --toolsets=core,playback
spotify-mcp --toolsets=all
```

---

## Environment Variables

| Variable | Required | Description |
|---|---|---|
| `SPOTIPY_CLIENT_ID` | ✅ | Spotify app Client ID |
| `SPOTIPY_REDIRECT_URI` | ✅ | Must match Spotify dashboard (default: `http://127.0.0.1:8888/callback`) |
| `TMDB_API_KEY` | Optional | TMDB v3 API key |
| `TMDB_READ_ACCESS_TOKEN` | Optional | TMDB v4 Bearer token (alternative to API key) |
| `SPOTIFY_TOOLSETS` | Optional | Comma-separated toolset list (e.g. `core,playback`, or `all` for every tool; default `core`) |
| `SPOTIFY_MCP_CACHE_PATH` | Optional | Spotify token cache file, shared with `spotify-mcp-web` (default `~/.spotify-mcp/.spotipyoauthcache`) |
| `OPEN_BROWSER` | Optional | Set to `true` to auto-open the Soundtrack Studio UI |
| `HOST` | Optional | Server bind host (default `0.0.0.0`, for `spotify-soundtrack-mcp`) |
| `PORT` | Optional | Server bind port (default `8080`, for `spotify-soundtrack-mcp`) |

---

## Links

- [GitHub Repository](https://github.com/Chiru144/Spotify-MCP-Web-MCP-Server)
- [Web App Package (spotify-mcp-web)](https://pypi.org/project/spotify-mcp-web/)
- [Report Issues](https://github.com/Chiru144/Spotify-MCP-Web-MCP-Server/issues)
