Spotify & TMDB Web MCP Server

This repository contains a FastMCP application integrating Spotify and TMDB (The Movie Database), powered by 43 registered MCP tools and 7 autonomous agent skills. It allows you to build custom soundtracks, automate playlist curation, explore listening taste, and interact with a local web-based Soundtrack Curator & Staging Studio.

Highlights

• 43 FastMCP Tools & 7 Agent Skills: Comprehensive toolkit covering cinema filmography discovery, smart playlist management, acoustic feature reordering, deep taste analytics, and complete Spotify Connect hardware control.

• Cross-Domain Media Blending: Bridges cinema and music by letting your AI dynamically look up movies, cast, or crew on TMDB and map them into custom Spotify playlists.

• Dual Web & Agent Design: Built on FastAPI/Uvicorn, it functions as both a flexible web endpoint and an MCP server, supporting remote hosting and multiple networked AI connections.

• Modular Architecture: The codebase is cleanly separated into specialized tool modules (playback.py, playlists.py, taste.py, search.py), making it highly scalable and completely unit-testable.

Related MCP server: Spotify MCP Server

Features

• Full Playback Control: Play, pause, skip, seek to specific times, adjust volume, toggle repeat/shuffle, switch active devices (Premium), and manage your queue.

• Smart Playlist Management: Create playlists, combine, dedupe, and intelligently reorder tracks based on audio features (e.g., sorting by energy arcs or valence).

• Search & Library Access: Search for tracks, albums, artists, or playlists on Spotify, and access your saved playlists.

• Deep Taste Analysis & Insights: Retrieve top played songs and artists (short/medium/long term), analyze deep audio features (danceability, valence, energy), and map related artist networks.

• TMDB Movie & Actor Search: Look up rich biographical profiles for actors or get release details, overviews, and ratings for movies directly from The Movie Database.

• Soundtrack Curator: Integrated with TMDB and DuckDuckGo to automatically discover an actor's filmography, find the corresponding soundtracks, and build a dedicated Spotify playlist.

• Soundtrack Staging Studio: A local web interface to visualize and manage your curated soundtracks.

Feature Comparison

Why use this server over standard Spotify MCP integrations? Most basic MCP servers only expose raw Spotify API endpoints without intelligence. This server bridges Spotify with TMDB cinema data, provides an interactive Web Soundtrack Curator Studio, and introduces advanced playlist curation algorithms:

Filmography & Cinema Soundtrack Pipeline

Unlike standard music-only integrations, this server deeply integrates TMDB (The Movie Database) with Spotify's library:

• Actor Filmography Discovery: Fetches full acting credits sorted by popularity or release date, with a resilient 3-tier fallback (TMDB $\rightarrow$ DuckDuckGo $\rightarrow$ Wikipedia).

• Soundtrack Resolution: Searches Spotify for official soundtracks and scores, falling back to track-level searches and DuckDuckGo tracklist discovery when albums are unlinked.

• Automated Curation: Creates dedicated actor or movie playlists in seconds (create_actor_playlist, add_movie_songs_to_playlist).

Vibe & Mood Sorting (audio_features)

Instead of arbitrary text labels, this server pulls standard audio feature scores ($0.0$ to $1.0$) for tracks:

• Valence: Positivity, musical cheerfulness, or sadness.

• Energy: Intensity, loudness, and fast-paced activity.

• Danceability: Rhythm stability, beat strength, and tempo consistency.

• Acousticness & Instrumentalness: Acoustic instrument usage vs. purely vocal/electronic elements.

Using these metrics, the AI calculates a track's "vibe profile". For example, a song with high valence and high energy is tagged by the LLM as "Upbeat Workout", while low valence and high acousticness is tagged as "Melancholic Chill".

Song & Type Suggestions (get_recommendations)

For song suggestions, it wraps Spotify's native Recommendations API, which accepts seed constraints (genres, audio targets, and seed tracks/artists).

Tools & Agent Skills Catalog

This server registers 43 specialized FastMCP tools and packages 7 dedicated agent skills for autonomous AI workflows:

🎬 Cinema & Filmography Tools

• create_actor_playlist(actor_name, ...): End-to-end automated pipeline to discover an actor's filmography, find the soundtracks on Spotify, and compile a dedicated playlist.

• search_actor_movies(actor_name, limit, sort_by): Discovers an actor's full filmography via TMDB with DuckDuckGo and Wikipedia fallback engines.

• get_actor_tmdb_profile(actor_name): Fetches rich actor biographical profiles, popularity metrics, and top known credits.

• search_movie_tmdb(movie_name, limit): Searches TMDB for movie details, release year, ratings, and synopses.

• get_movie_songs(movie_name, limit): Searches Spotify for soundtrack albums and songs from a movie with DuckDuckGo fallback assistance.

• add_movie_songs_to_playlist(playlist_id, movie_name, max_songs): Finds songs from a movie on Spotify and appends them directly to an existing playlist.

• search_duckduckgo(query, max_results): Autonomous web search engine for discovering movie tracklists, niche soundtracks, and music news.

🎵 Smart Playlist Management Tools

• create_playlist(name, description, public): Creates a new Spotify playlist for the user.

• shuffle_playlist(playlist_id): Mixes and shuffles all songs in a playlist into a completely new random permutation.

• reorder_playlist_by_audio_features(playlist_id, feature, order): Sorts tracks by acoustic properties (energy, valence, danceability, tempo, etc.) in ascending or descending order.

• dedupe_playlist(playlist_id): In-place scan and removal of duplicate songs from a playlist, preserving the first instance.

• combine_playlists(playlist_ids, new_name, description): Merges multiple playlists into a unified, deduplicated playlist with automated pagination.

• add_tracks_to_playlist(playlist_id, track_uris): Adds track URIs in batches of 100 with deduplication checks.

• get_user_playlists(limit): Retrieves user-owned playlists with track counts and URIs.

• get_playlist_tracks(playlist_id, limit, offset): Inspects songs currently inside a playlist.

• update_playlist(playlist_id, name, description, public): Updates playlist metadata.

• remove_tracks_from_playlist(playlist_id, uris): Removes specific track URIs from a playlist.

✨ Taste Analysis & Recommendation Engine

• get_recommendations(seeds..., targets...): Multi-seed recommendation engine supporting up to 5 combined seeds (genres, tracks, artists) and 6 fine-grained acoustic targets (valence, energy, danceability, acousticness, instrumentalness, tempo).

• get_audio_features(track_uris): Extracts deep acoustic scores ($0.0 - 1.0$), BPM, key, and musical mode for up to 100 tracks.

• get_user_top_tracks(limit, time_range): Retrieves top songs across short (~4 weeks), medium (~6 months), and long-term (years) horizons.

• get_user_top_artists(limit, time_range): Retrieves top artists across short, medium, and long-term listening history.

• get_artist_network(artist_name_or_id): Maps related artist networks and sub-genres.

• get_saved_tracks(limit, offset): Queries songs saved in the user's personal Spotify Library.

• search_spotify(query, search_type, limit): Flexible search across Spotify tracks, albums, artists, or playlists.

🎛️ Playback & Hardware Controls

• get_current_playback(): Returns currently playing track, artist, album, progress, and active device.

• play_track(device_id, uris, uri): Starts or resumes music playback on Spotify.

• pause_playback(device_id): Pauses active music playback.

• next_track(device_id) / previous_track(device_id): Skips tracks forward or backward.

• seek_to_position(position_ms, device_id): Seeks to a specific millisecond in the active track.

• set_volume(volume_percent, device_id): Sets playback volume level (0 to 100%).

• set_repeat_mode(state, device_id): Sets repeat mode (off, track, context).

• toggle_shuffle(state, device_id): Toggles Spotify player shuffle mode.

• get_available_devices(): Lists active and discovered Spotify Connect hardware devices.

• transfer_playback(device_id, play): Seamlessly switches audio playback to another device.

• add_to_queue(uri, device_id): Enqueues a song to the user's upcoming playback queue.

• get_user_queue(): Inspects currently playing track and the queue.

• open_soundtrack_studio(): Launches or opens the visual Soundtrack Curator & Staging Studio web UI.

🤖 Autonomous Agent Skills (skills/)

These skills are automatically injected into connecting MCP clients on startup:

• actor-filmography-searcher.md: Guides the AI to query TMDB and present an actor's filmography with character roles and release years.

• movie-soundtrack-adder.md: Specialized agent workflow to identify movie tracks and append them into user playlists.

• playlist-vibe-sorter.md: Teaches the agent to re-sort playlists according to musical flow (e.g. build up energy or cool down).

• playlist-deduplicator.md: Step-by-step cleanup protocol to identify duplicate tracks and sanitize playlists in-place.

• taste-analyzer.md: Guides AI to examine short/medium/long-term listening data and provide personalized listening profiles.

• playback-controller.md: Natural language translation for playback control and multi-device routing.

• browser-song-tagger.md: Autonomous agent skill using DuckDuckGo web search to research obscure song genres/cultural tags and auto-tag Spotify playlists.

Prerequisites

Before running the application, make sure you have the following installed:

• Python 3.10+

• Git

You will also need Developer API Keys for:

• Spotify Developer Dashboard

• TMDB API

Installation & Setup

Follow these steps to get the project running locally:

1. Clone the repository

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

2. Create and activate a Virtual Environment

It is recommended to use a virtual environment to manage 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 the requirements.txt file:

pip install -r requirements.txt

4. Configure Environment Variables

Create a file named .env in the root of the project directory. You need to add your API credentials from Spotify and TMDB.

Here is the .env template:

# Spotify Credentials
SPOTIPY_CLIENT_ID=your_spotify_client_id
SPOTIPY_CLIENT_SECRET=your_spotify_client_secret
SPOTIPY_REDIRECT_URI=http://localhost:8080 # Or your configured redirect URI

# TMDB Credentials
TMDB_API_KEY=your_tmdb_api_key
TMDB_READ_ACCESS_TOKEN=your_tmdb_read_access_token
TMDB_ACCESS_TOKEN=your_tmdb_access_token

# Optional configuration
OPEN_BROWSER=true

Make sure to replace your_* placeholders with the actual keys from your developer dashboards.

Running the Application

There are two entry points to run the server, depending on your use case:

1. server.py (Development & Web App Focus)

Start the MCP server and background web app simultaneously by running:

python server.py

The application will start, and the web interface should automatically open in your default browser at http://127.0.0.1:8000.

2. mcp.py (MCP Client Integration Focus)

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

python mcp.py

Why mcp.py? Standard MCP uses standard input/output (stdio) for communication. When Spotify requires you to log in for the first time, it normally pauses and asks you to paste a redirect URL in the terminal. This breaks the MCP protocol. mcp.py solves this by launching a Tkinter GUI popup for the Spotify authentication process, ensuring stdio remains clean and unblocked for the MCP client.

API Limits

Please keep in mind the rate limits imposed by the external APIs used in this project:

• Spotify Web API: Spotify uses a dynamic rate limit based on a rolling window. If you make too many requests in a short period (such as aggressively searching or curating massive playlists), you will receive a 429 Too Many Requests response. The app may need to back off and try again later.

• TMDB API: The Movie Database allows up to 50 requests per second. This is generally quite generous for normal usage, but batch queries or rapid concurrent lookups could potentially hit this limit.

MCP Integration

This project is built using fastmcp. Once running via stdio (or SSE if configured), it can be seamlessly consumed by other MCP clients.