Spotify & TMDB Web and MCP Server

This repository contains a FastMCP application that connects Spotify with TMDB (The Movie Database). It has 115 registered MCP tools and 20 autonomous agent skills, and lets you build movie soundtrack playlists, automate playlist curation, explore your listening taste, and use a local web app, the Soundtrack Curator & Staging Studio.

[!NOTE]
Built mostly for Indian users. The project is designed around Indian film music: it builds playlists from an actor's filmography and matches soundtracks for Kannada, Telugu, Tamil, Malayalam and Hindi movies, including songs credited as 'From "Movie Name"' and releases tagged with a language, such as "[Kannada]". It works for any music on Spotify, but Indian cinema is where it is strongest.

Highlights

• 115 FastMCP Tools & 20 Agent Skills: Covers cinema filmography discovery, smart playlist management, artist-network and mood discovery, a local library cache, vibe/radio/era/time-capsule playlist generators, taste analytics, catalog browsing, library management, and full Spotify Connect device control.
• PKCE OAuth & Flexible Auth: Spotify sign-in uses PKCE, so you only need a Client ID and a one-click browser login, with no client secret. TMDB accepts either an API key or a Read Access Token.
• Cinema Meets Music: Your AI assistant can look up movies, cast and crew on TMDB and turn them into Spotify playlists.
• Dual Web & Agent Design: Built on FastAPI and Uvicorn, it runs both as a web app and as an MCP server, and supports remote hosting and several AI clients at once.
• Modular Architecture: The tools are split into focused modules (playback.py, playlists.py, taste.py, search.py, library.py, library_cache.py, generators.py, browse.py, web_app.py), each covered by unit tests.

Spotify 2026 Development Mode Limits

In 2026, Spotify switched off several Web API features for apps in Development Mode, which is what every personal Client ID is. The tools work around them where they can:

Local Library Cache & Playlist Generators

spotify_sync_library downloads your Liked Songs and the playlists you own into a JSON file: ~/.cache/spotify-mcp/library.json, or %LOCALAPPDATA%\spotify-mcp\library.json on Windows (set SPOTIFY_MCP_LIBRARY_PATH to change it). After that:

• spotify_query_library and spotify_library_stats answer questions about your music without calling Spotify.
• spotify_vibe_playlist builds a playlist for a mood, or an energy/valence target, from songs you already like.
• spotify_era_playlist (with from_library=True) and spotify_time_capsule_playlist (songs you saved in a given year) also use the cache.
• spotify_radio_playlist mixes an artist's songs with songs by the artists they collaborate with.

Every generator shows a preview first and only creates a playlist when called with create=True.

How vibes are estimated: Spotify no longer gives this app audio features or artist genres, so each genre has an estimated energy and valence (GENRE_VIBES in tools/discovery.py). A song gets its vibe from the genre searches its artist appears in, plus words in its track, album and playlist names ("Unplugged" means acoustic; a playlist called "Gym" means workout). Spotify's genre search mostly covers mainstream Western genres, so songs from other scenes, such as Kannada, Telugu or Tamil film music, are often left unplaced. Naming your playlists by mood helps.

Run spotify_sync_library again whenever your library changes. A sync makes about one Spotify call per 50 Liked Songs, plus one or more per playlist.

Features & Capabilities

For an in-depth breakdown of the features, a feature comparison table, and the cinema filmography pipeline, see CONTRIBUTING.md. The complete 115-tool catalog and the 20 agent skills are listed in CONTRIBUTING.md.

Install from PyPI

The MCP server is listed in the official MCP Registry as io.github.Chiru144/spotify-soundtrack-mcp (metadata in server.json), so registry-aware MCP clients can find and install it. The server and the web studio are published as two Python packages:

1. Install

pip install spotify-soundtrack-mcp spotify-mcp-web

You need Python 3.10 or later. Installing spotify-mcp-web also installs spotify-soundtrack-mcp. If you don't want the web studio, install only spotify-soundtrack-mcp.

2. Configure

Create ~/.spotify-mcp/.env (or a .env file in the folder you run the commands from):

SPOTIPY_CLIENT_ID=your_spotify_client_id
SPOTIPY_REDIRECT_URI=http://127.0.0.1:8888/callback
TMDB_API_KEY=your_tmdb_api_key            # or TMDB_READ_ACCESS_TOKEN=...
SPOTIFY_TOOLSETS=core                     # optional: core (default), playback, playlists, search, taste, library, browse, all

In the Spotify Developer Dashboard, add http://127.0.0.1:8888/callback as a Redirect URI for your app. Only the Client ID is needed; there is no client secret.

3. Connect your Spotify account

spotify-mcp-auth

This opens Spotify in your browser. Once you approve, the token is saved to ~/.spotify-mcp/.spotipyoauthcache (set SPOTIFY_MCP_CACHE_PATH to store it elsewhere), and both the MCP server and the web studio use it.

4. Connect the MCP server to your AI client

spotify-mcp runs the server over stdio. Add it to Claude Desktop (claude_desktop_config.json), Cursor (.cursor/mcp.json) or any other MCP client:

{
  "mcpServers": {
    "spotify": {
      "command": "spotify-mcp",
      "env": {
        "SPOTIFY_TOOLSETS": "core"
      }
    }
  }
}

If the client can't find spotify-mcp on your PATH, use the full path printed by where spotify-mcp (Windows) or which spotify-mcp (macOS/Linux). With uv, you can skip the install and let the client run it:

{
  "mcpServers": {
    "spotify": {
      "command": "uvx",
      "args": ["--from", "spotify-soundtrack-mcp", "spotify-mcp"]
    }
  }
}

From version 1.1.0, the package-named command also runs over stdio when given --transport stdio. This is the command MCP Registry clients run:

{
  "mcpServers": {
    "spotify": {
      "command": "uvx",
      "args": ["spotify-soundtrack-mcp", "--transport", "stdio"],
      "env": {
        "SPOTIPY_CLIENT_ID": "your_spotify_client_id"
      }
    }
  }
}

While spotify-mcp is running, it also starts the web studio at http://127.0.0.1:8000 if spotify-mcp-web is installed.

To serve MCP over HTTP (SSE) for remote clients instead, run:

spotify-soundtrack-mcp

It listens on 0.0.0.0:8080; set HOST and PORT to change this. spotify-soundtrack-mcp --transport stdio (or MCP_TRANSPORT=stdio) runs it over stdio instead, and spotify-soundtrack-mcp --version prints the installed version.

5. Open the web studio on its own

soundtrack-studio

This starts the studio at http://127.0.0.1:8000 and opens your browser. Set PORT to use a different port, or OPEN_BROWSER=false to stop it from opening the browser. The tool guide is at /guide and the advanced tools are at /tools.

Prerequisites

To run from source instead of PyPI, make sure you have the following installed:

• Python 3.10+
• Git

You will also need developer API credentials for:

• Spotify Developer Dashboard (only the Client ID is needed; sign-in uses PKCE browser authorization)
• TMDB API (provide either an API key or a Read Access Token)

Installation & Setup

Follow these steps to run the project locally:

1. Clone the repository

git clone https://github.com/Chiru144/Spotify-MCP-Web-And-MCP-Server.git
cd Spotify-MCP-Web-And-MCP-Server

2. Create and activate a virtual environment

Using a virtual environment is recommended for managing dependencies.

Windows:

python -m venv .venv
.venv\Scripts\activate

Mac/Linux:

python3 -m venv .venv
source .venv/bin/activate

3. Install dependencies

Install the required Python packages from requirements.txt:

pip install -r requirements.txt

4. Configure environment variables

Create a file named .env in the project root (or copy .env.sample) and add your API credentials:

# Spotify Developer API credentials (PKCE auth - no secret needed)
SPOTIPY_CLIENT_ID=your_spotify_client_id
SPOTIPY_REDIRECT_URI=http://127.0.0.1:8888/callback

# TMDB credentials - provide ANY ONE (either TMDB_API_KEY or TMDB_READ_ACCESS_TOKEN):
TMDB_API_KEY=your_tmdb_api_key
TMDB_READ_ACCESS_TOKEN=your_tmdb_read_access_token
TMDB_BASE_URL=https://api.themoviedb.org/3

# Modular toolsets: choose which tools to load, to avoid overloading the LLM's context window
# Options: core (default, 16 essential curation tools), playback, playlists, search, taste, library, browse, or all
SPOTIFY_TOOLSETS=core

# Optional configuration
OPEN_BROWSER=true

[!TIP]

• Spotify PKCE flow: The app uses PKCE (Proof Key for Code Exchange) authorization. No client secret is needed or used; you only need your SPOTIPY_CLIENT_ID and a one-click browser login.
• Flexible TMDB authentication: You only need one of TMDB_API_KEY (v3 API key) or TMDB_READ_ACCESS_TOKEN (v4 Read Access Token). The server detects which one you provided.

5. (Optional) Verify Spotify sign-in

Run the one-click Spotify authorization script to test your connection:

python auth_spotify.py

Modular Toolsets & On-Demand Lazy Loading

To avoid flooding the LLM context window in AI clients (Cursor, Claude Desktop, Antigravity), this server uses modular toolsets and on-demand lazy loading:

• Context window protection: The full catalog of 115 tools takes ~25,600 tokens. Running with --toolsets=core exposes only the 16 essential curation tools (~4,100 tokens), an 84% reduction.
• On-demand lazy loading: Heavy modules (spotipy, requests, bs4, ddgs, etc.) are not loaded at startup. When an LLM calls a tool, its module is imported and kept in memory, so later calls start instantly.

Available Toolsets

Running with Toolset Flags

You can choose toolsets with the --toolsets=... command-line flag or the SPOTIFY_TOOLSETS environment variable:

# Run with the lightweight core toolset (16 tools, best for Cursor/Claude):
python server.py --toolsets=core
python mcp.py --toolsets=core

# Combine multiple toolsets:
python server.py --toolsets=core,playback

# Run with the complete catalog (115 tools):
python server.py --toolsets=all

Running the Application

There are two entry points, depending on how you want to use the server:

1. server.py (development and web app)

Start the MCP server and the web app together:

python server.py --toolsets=core

The web interface should open automatically in your default browser at http://127.0.0.1:8000.

2. mcp.py (MCP client integration)

If you are running this project as a tool inside an MCP host (such as Cursor, VS Code, or Claude Desktop), use mcp.py:

python mcp.py --toolsets=core

Repository Structure

Spotify-MCP-Web-And-MCP-Server/
├── server.json                # MCP Registry listing (io.github.Chiru144/spotify-soundtrack-mcp)
├── server.py                  # FastMCP server entry point & SSE ASGI app
├── mcp.py                     # Stdio FastMCP runner with PKCE GUI OAuth popup
├── auth_spotify.py            # CLI helper to verify the Spotify OAuth connection
├── requirements.txt           # Python dependencies
├── SPOTIFY_RULES.md           # MCP tool usage rules & agent clarification protocol
├── tools/                     # Modular MCP tool implementations (115 tools)
│   ├── registry.py            # Toolset catalog, CLI toolset router & lazy loader
│   ├── core.py                # FastMCP server instance, Spotify/TMDB client helpers
│   ├── spotify_client.py      # Spotify client with rate-limit handling & 2026 API fixes
│   ├── playlists.py           # Core playlist curation & power tools
│   ├── playback.py            # Spotify Connect playback & device controls
│   ├── taste.py               # Taste analytics & listening trends
│   ├── search.py              # Music discovery, search & TMDB filmography tools
│   ├── library.py             # Saved tracks, albums & library management
│   ├── library_cache.py       # Local JSON cache of Liked Songs & your playlists
│   ├── generators.py          # Vibe, radio, era & time-capsule playlist generators
│   ├── discovery.py           # Search-based discovery & genre vibe estimates (2026 API workarounds)
│   ├── browse.py              # Catalog entity inspection & artist discography
│   ├── tmdb_helpers.py        # TMDB API client & DuckDuckGo/Wikipedia fallbacks
│   ├── web_app.py             # MCP tool that opens the Soundtrack Studio UI
│   └── web_app_internal.py    # Background thread launcher for Soundtrack Studio
├── mcp-soundtrack-app/        # Soundtrack Curator & Staging Studio web app
│   ├── server.py              # FastAPI server for the REST API & web pages
│   └── templates/             # HTML templates
│       ├── index.html         # Main Soundtrack Curator & Staging Studio UI
│       ├── tools.html         # Advanced tools dashboard
│       └── guide.html         # Tool guide & documentation
├── skills/                    # 20 autonomous agent skills for AI assistants
├── packaging/                 # PyPI packaging for both packages
│   ├── build_packages.py      # Builds the wheels, checks and bumps versions
│   ├── spotify-soundtrack-mcp/ # pyproject, PyPI README and CLI of the MCP server package
│   └── spotify-mcp-web/       # pyproject, PyPI README and CLI of the web studio package
├── tests/                     # Pytest unit & integration tests
│   ├── test_browse.py
│   ├── test_discovery.py
│   ├── test_library.py
│   ├── test_library_cache.py
│   ├── test_playback.py
│   ├── test_playlists.py
│   ├── test_search.py
│   ├── test_server.py
│   ├── test_spotify_client.py
│   ├── test_studio_playlists.py
│   ├── test_taste.py
│   ├── test_toolsets.py
│   └── test_web_app.py
├── .cursor/rules/             # Cursor IDE rules
├── .agents/rules/             # Agent / Antigravity IDE rules
└── .github/                   # Copilot instructions & the release workflow (workflows/publish.yml)

API Limits

Keep in mind the rate limits of the external APIs this project uses:

• Spotify Web API: Spotify uses a dynamic rate limit over a rolling window. If you make too many requests in a short time (for example, searching aggressively or building very large playlists), Spotify returns 429 Too Many Requests and may ask the app to wait, sometimes for hours. When the wait is long, the tools stop and tell you when you can try again instead of hanging.
• TMDB API: The Movie Database allows up to 50 requests per second. That is generous for normal use, but large batches or many rapid lookups at once can still hit it.

MCP Integration

This project is built with fastmcp. Once it is running over stdio (or SSE, if configured), any MCP client can use its tools.

Publishing a Release (PyPI & MCP Registry)

The two PyPI packages are built from this repository by packaging/build_packages.py, which copies tools/, skills/, SPOTIFY_RULES.md and mcp-soundtrack-app/ into the package layouts and rewrites the tools.* imports to spotify_soundtrack_mcp.tools.*.

pip install build
python packaging/build_packages.py --check              # versions, server.json and mcp-name agree
python packaging/build_packages.py                      # build wheels and sdists into dist/
python packaging/build_packages.py --set-version 1.2.0  # bump both packages and server.json

Pushing a tag such as v1.2.0 runs .github/workflows/publish.yml, which tests and builds both packages, uploads them to PyPI, and then publishes server.json to the MCP Registry.

One-time setup:

1. PyPI trusted publishing: on PyPI, open each project (spotify-soundtrack-mcp and spotify-mcp-web) → Manage → Publishing → Add a new publisher → GitHub, with owner Chiru144, repository Spotify-MCP-Web-And-MCP-Server, workflow publish.yml and environment pypi.
2. GitHub environment: in the repository settings, create an environment named pypi.
3. MCP Registry: nothing to configure. The workflow signs in with GitHub OIDC, which allows publishing names under io.github.Chiru144/.

The registry confirms you own the PyPI package by finding mcp-name: io.github.Chiru144/spotify-soundtrack-mcp in its PyPI description, which comes from packaging/spotify-soundtrack-mcp/README.md. Keep that line when editing the README.

To publish by hand instead:

python packaging/build_packages.py
twine upload dist/spotify-soundtrack-mcp/* dist/spotify-mcp-web/*
mcp-publisher login github     # https://github.com/modelcontextprotocol/registry/releases
mcp-publisher publish          # run from the repository root, next to server.json