Metadata-Version: 2.5
Name: spotify-mcp-web
Version: 1.0.0
Summary: Soundtrack Curator & Staging Studio — a self-hosted FastAPI web app for Spotify playlist curation, TMDB filmography, and MCP tools management.
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: fastapi,mcp,playlist,soundtrack,spotify,studio,tmdb,web
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
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 :: WSGI :: Application
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: pydantic>=2.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: requests>=2.32.0
Requires-Dist: spotify-soundtrack-mcp>=1.0.0
Requires-Dist: spotipy>=2.26.0
Requires-Dist: uvicorn>=0.30.0
Description-Content-Type: text/markdown

# spotify-mcp-web

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

> **Soundtrack Curator & Staging Studio** — a self-hosted FastAPI web application for Spotify playlist curation, TMDB filmography browsing, and MCP tools management. Pairs with [spotify-soundtrack-mcp](https://pypi.org/project/spotify-soundtrack-mcp/).

---

## Installation

```bash
pip install spotify-mcp-web
```

---

## Quick Start

### 1. Configure credentials

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

```env
# Spotify Developer App credentials (PKCE — no secret needed!)
SPOTIPY_CLIENT_ID=your_spotify_client_id_here
SPOTIPY_REDIRECT_URI=http://127.0.0.1:8888/callback

# TMDB (optional, enables cinema/filmography features)
TMDB_API_KEY=your_tmdb_api_key_here
```

> **Important:** In your [Spotify Developer Dashboard](https://developer.spotify.com/dashboard), add `http://127.0.0.1:8888/callback` as a Redirect URI.

### 2. Start the Studio

```bash
soundtrack-studio
```

This starts the web app at **http://127.0.0.1:8000** and opens it in your browser automatically.

---

## Features

- 🎬 **Cinema Filmography** — Search actors/movies via TMDB and build soundtracks automatically
- 🎵 **Playlist Curation** — Create, merge, deduplicate, sort, split, and export Spotify playlists
- 🎚️ **Playback Controls** — Control Spotify Connect devices, queue management, volume/shuffle/repeat
- 📊 **Taste Analytics** — Top tracks, artists, listening patterns, playlist comparisons
- 📚 **Library Management** — Saved tracks & albums, library browsing
- 🔍 **Catalog Browsing** — Artist, album, and track lookup

---

## 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) |
| `HOST` | Optional | Bind host (default `127.0.0.1`) |
| `PORT` | Optional | Bind port (default `8000`) |
| `OPEN_BROWSER` | Optional | Set to `false` to suppress auto-open |
| `SOUNDTRACK_TEMPLATES_DIR` | Optional | Custom path to HTML templates directory |

---

## Running as a Remote Server

```bash
HOST=0.0.0.0 PORT=8080 OPEN_BROWSER=false soundtrack-studio
```

---

## Pairing with the MCP Agent

Install both packages to get the full experience:

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

- `spotify-mcp` — starts the agent (for Claude Desktop / Cursor)
- `soundtrack-studio` — starts the web UI

---

## Links

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