# Spotify MCP Server (`rl1987/spotify-mcp-server`) Actor

Model Context Protocol (MCP) server exposing the Spotify Web API, with OAuth 2.0 Authorization Code + PKCE login for user accounts.

- **URL**: https://apify.com/rl1987/spotify-mcp-server.md
- **Developed by:** [R.L.](https://apify.com/rl1987) (community)
- **Categories:** MCP servers
- **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per usage

This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-usage

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

### Spotify MCP Server

Control your **Spotify** account straight from your AI assistant. Ask it to search for a song and
play it on your speaker, build you a playlist and add tracks to it, tell you what's currently
playing, follow an artist, or check what you've been listening to lately - all through plain
conversation, no Spotify app tab-switching required.

This is a [Model Context Protocol](https://modelcontextprotocol.io) server, so it plugs straight
into Claude, ChatGPT, or any other MCP-compatible assistant. It runs on Apify and stays always-on,
so there's no server to babysit and no "cold start" wait - you connect once and it's ready.

### Why use this?

- **Talk instead of click.** "Play something upbeat", "add the last three Beatles songs I searched
  to my road trip playlist", "who am I following that I haven't listened to in a while" - your
  assistant does the clicking.
- **Your whole library and playback, not just search.** Playlists (create, edit, reorder, cover
  art), saved tracks/albums/shows/episodes/audiobooks, followed artists, top artists/tracks, and
  full playback control (play, pause, skip, volume, shuffle, queue) on whichever device you're
  signed into.
- **Nothing extra to build or host.** No app to write, no server to run - connect your assistant to
  the URL below and the tools just show up.
- **Your account stays yours.** Logging in happens on Spotify's own real login page, the same one
  you already trust, with the standard secure login method Spotify recommends for apps like this.
  This server never sees or stores your Spotify password.

### Getting started

1. Connect your assistant to this actor (see **Connecting an MCP client** below).
2. Register your own free Spotify app (two minutes, no approval needed - see **Set up your Spotify
   app** below) and give its credentials to your assistant to configure.
3. Ask it to log you into Spotify. It'll hand you a real `accounts.spotify.com` link - open it,
   log in, and approve access.
4. Spotify sends you back a short code. Give that code to your assistant to finish connecting your
   account (a one-time copy/paste step - see below for why).
5. You're set. Ask for anything: "what's playing right now", "make a playlist called Focus and add
   some lo-fi to it", "pause my music".

You can disconnect any time by asking your assistant to log you out.

#### Set up your Spotify app

This server is shared by everyone who uses it on Apify - there's no single built-in Spotify app
that could work for every user, because Spotify caps how many people can use one app before its
developer requests extended access. So each person connects their **own** free app instead - same
one-time step you'd do for any "connect your Spotify" integration you self-host:

1. Go to the [Spotify Developer Dashboard](https://developer.spotify.com/dashboard) and create an
   app (any name/description works - this is just your personal API key, not a public listing).
2. In the app's Settings, add this exact Redirect URI:
   `https://rl1987--spotify-mcp-server.apify.actor/callback`
3. Copy the app's **Client ID** and **Client Secret**.
4. Ask your assistant to call `spotify_configure` with those two values. This only needs doing
   once per conversation/session - after that, every other tool (search, login, playback, ...)
   just works.

Your Client ID/Secret are encrypted at rest, scoped to your session only, and never shared with
other users of this server.

#### About the copy/paste login step

Most "click to log in" integrations redirect you straight back automatically. Here, Apify's hosting
platform requires every request to carry proof of who's calling it, and Spotify's redirect back to
this server can't carry that proof - so after you approve access, the browser lands on a page
showing a raw error like `{"error": {"type": "api-token-missing", ...}}`. **That error is
expected - it does not mean the login failed.** What you need is already in the address bar at
that point: a `code=...` and `state=...` query string. Copy those two values and pass them back to
your assistant. It's the same fallback approach tools like `gh` (GitHub's CLI) or `gcloud` use when a browser can't talk
directly to the tool that started the login. One extra step, same secure login underneath.

### Connecting an MCP client

```
claude mcp add --transport http spotify https://rl1987--spotify-mcp-server.apify.actor/mcp \
  --header "Authorization: Bearer <YOUR_APIFY_API_TOKEN>"
```

- Actor page: https://console.apify.com/actors/NfIkvgP2Og5cscmTE
- MCP endpoint: https://rl1987--spotify-mcp-server.apify.actor/mcp

The Bearer token is your own Apify API token (from your [Apify account
settings](https://console.apify.com/settings/integrations)) - it's how Apify knows who's connecting
and bills your usage. It has nothing to do with your Spotify login. Verify the connection with
`claude mcp list` or `/mcp`.

### What you can ask for

| Category | What it covers |
|---|---|
| Search & browse | Songs, artists, albums, podcasts, episodes, audiobooks |
| Your library | Save/remove/check tracks, albums, shows, episodes, audiobooks |
| Playlists | Create, edit, reorder tracks, upload cover art, view any playlist |
| Following | See and manage the artists you follow |
| Your profile & taste | Your profile info, top artists/tracks, recently played |
| Playback | Play, pause, skip, seek, volume, shuffle, repeat, queue, switch devices |

Every tool needs `spotify_configure` done first (your own app credentials). Beyond that, public
search/browse works with just that. Anything tied to your account (library, playlists you own,
playback, profile) also needs the one-time login above.

### Cost

Each request your assistant makes through this server costs a small flat fee, billed to your Apify
account - you only pay for what you actually use, nothing failed or unused. See
[pay\_per\_event.json](.actor/pay_per_event.json) for the exact rate.

### FAQ

**Why do I need to register my own Spotify app instead of it just working?** Spotify limits how
many end users can authorize a single app before its developer requests (and qualifies for)
extended production access - which requires being an established business with a large existing
user base. A shared community server like this one can't meet that bar, so instead everyone brings
their own free app. It's a two-minute signup with no approval wait, and it's the same thing you'd
do to self-host any "connect your Spotify" integration.

**Do I need my own Spotify Premium account for playback control?** Spotify requires Premium for
the play/pause/skip/volume/queue endpoints; free accounts can still search, browse, and manage
their library/playlists.

**What if Spotify is slow to respond or rate-limits a request?** The server automatically retries
with backoff and only bothers you if it genuinely can't get through, so you don't need to retry
things yourself.

**Can I use this with a team?** Yes - a shared MCP connection URL can be committed to a team repo;
each teammate connects with their own Apify token and logs into their own Spotify account
independently.

### Resources

- [Spotify Web API reference](https://developer.spotify.com/documentation/web-api)
- [Apify Actor Standby mode](https://docs.apify.com/platform/actors/development/programming-interface/standby)

# Actor input Schema

## Actor input object example

```json
{}
```

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {};

// Run the Actor and wait for it to finish
const run = await client.actor("rl1987/spotify-mcp-server").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {}

# Run the Actor and wait for it to finish
run = client.actor("rl1987/spotify-mcp-server").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{}' |
apify call rl1987/spotify-mcp-server --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,rl1987/spotify-mcp-server"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/NfIkvgP2Og5cscmTE/builds/i8d1SXS2igX6Hspbh/openapi.json