Skip to content
Back to search

dj-mcp

SkillWorks with Claude CodeGitHub

An MCP server for controlling playback with the Spotify Web API: search, Spotify Connect playback control (play/pause/skip/volume/queue/transfer), listening history, top items, and playlist creation. Authorization Code + PKCE with your own Spotify app (no client secret). Zero-dependency Node stdio server plus a CLI over the same core. Not affiliated with or endorsed by Spotify.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/kenjitayama--dj-mcp/badge.svg)](/listings/kenjitayama--dj-mcp)

HTML

<a href="/listings/kenjitayama--dj-mcp"><img src="/api/listings/kenjitayama--dj-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

**For users:** give your AI agent (Codex, Claude, Cursor, Grok Bot, or similar) this repo URL and ask it to set it up: "Set this up: https://github.com/kenjitayama/dj-mcp". The agent can handle the rest except three steps that need you:

1. **Have Spotify Premium.** Playback control requires it. 2. **Create your own Spotify app** in the [Developer Dashboard](https://developer.spotify.com/dashboard), with Redirect URI `http://127.0.0.1:8888/callback` and **Web API** checked. Give the agent its Client ID. Each person or app uses its own Client ID, and no client secret is needed. Details: [1. Create a Spotify app](#1-create-a-spotify-app). 3. **Approve in the browser.** Open the link the agent shows you and click Agree. You'll land on a "can't connect" page, which is expected. Copy the **full URL** from the address bar and paste it back to the agent within a few minutes, before the code expires.

**For agents**, step by step: 1. Check `node --version` is >= 20. 2. Run `git clone https://github.com/kenjitayama/dj-mcp /path/to/dj-mcp`. Below, `CLI` means `/path/to/dj-mcp/bin/dj-mcp`. 3. Save the user's Client ID, either as env `SPOTIFY_CLIENT_ID` or in `~/.config/dj-mcp/config.json` (folder 0700, file 0600). See [2. Set the Client ID](#2-set-the-client-id). 4. Run `CLI auth_start` and show the user the `authorize_url`. 5. Run `CLI auth_complete --redirect_url '<pasted URL>'`. Single-quote the URL, because it contains `&`. 6. Run `CLI auth_status` and confirm `authorized: true` and `missing_scopes: []`. 7. Run `CLI get_devices`. Devices only appear while a Spotify app is open, so if the list is empty, ask the user to open one. 8. With the user's OK, test playback: `CLI search --query '<song>'`, then `CLI transfer_playback --device_name '<name>'` and `CLI play --json '{"uris":["<track uri>"]}'`. 9. Register the MCP server (`node /path/to/dj-mcp/bin/dj-mcp-server`) with the user's client: - **Cursor / Claude Desktop:** see [Cursor](#cursor) and [Claude Desktop](#claude-desktop). - **Claude Code:** `claude mcp add --transport stdio --scope user dj-mcp -- node /path/to/dj-mcp/bin/dj-mcp-server` - **Codex:** `codex mcp add dj-mcp -- node /path/to/dj-mcp/bin/dj-mcp-server`, or in `~/.codex/config.toml`: ```toml [mcp_servers.dj-mcp] command = "node" args = ["/path/to/dj-mcp/bin/dj-mcp-server"] ``` - **Anything else:** see [MCP: generic stdio](#mcp-generic-stdio).

If the Client ID is in `config.json`, no env setting is needed in the client config.

**Rules for agents:** - Never commit tokens or the Client ID to the repo, and never paste them into it. - Don't print tokens. - Don't ask for a client secret. It isn't needed. - Don't re-run `auth_start` while an authorization is pending, because it invalidates the earlier link.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

plugin.json · Manifest · 34 lines
  1. {
  2. "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  3. "name": "dj-mcp",
  4. "version": "0.2.0",
  5. "description": "An MCP server for controlling playback with the Spotify Web API: search, Spotify Connect playback control (play/pause/skip/volume/queue/transfer), listening history, top items, and playlist creation. Authorization Code + PKCE with your own Spotify app (no client secret). Zero-dependency Node stdio server plus a CLI over the same core. Not affiliated with or endorsed by Spotify.",
  6. "author": {
  7. "name": "Kenji Tayama"
  8. },
  9. "homepage": "https://github.com/kenjitayama/dj-mcp",
  10. "repository": "https://github.com/kenjitayama/dj-mcp",
  11. "license": "MIT",
  12. "keywords": [
  13. "mcp",
  14. "music",
  15. "dj",
  16. "playback",
  17. "spotify-web-api",
  18. "agent-plugin"
  19. ],
  20. "extensions": {
  21. "com.cursor": {
  22. "variables": {
  23. "type": "object",
  24. "properties": {
  25. "SPOTIFY_CLIENT_ID": {
  26. "type": "string",
  27. "title": "Spotify Client ID",
  28. "description": "Client ID of your own Spotify developer app (public, not a secret). Optional if client_id is set in ~/.config/dj-mcp/config.json."
  29. }
  30. }
  31. }
  32. }
  33. }
  34. }
README.md · README · 227 lines
  1. # dj-mcp
  2. An MCP server for controlling playback with the Spotify Web API. `dj-mcp` is packaged as an
  3. [Agent Plugin](https://agent-plugins.org) (a stdio MCP server plus a skill) and ships a CLI over the same core,
  4. so AI agents can search music and play it on your Spotify Connect devices (desktop app, phone, speakers).
  5. Currently supports Spotify. In the future, I'd like to consider supporting other music services such as Apple Music.
  6. - Zero dependencies. Node.js >= 20. All logic is in `lib/core.mjs`.
  7. - Auth: Authorization Code + PKCE (S256) with **your own** Spotify app. No client secret.
  8. - Results come back trimmed to small, stable shapes, not raw Spotify JSON.
  9. - Tokens are stored outside the repo in `~/.config/dj-mcp/` (directory 0700, files 0600, atomic writes).
  10. The access token refreshes automatically (early, and once on a 401). Rotated refresh tokens are saved.
  11. On HTTP 429 it waits for `Retry-After` (≤30 s, up to 2 retries), otherwise it returns a `rate_limited` error.
  12. > dj-mcp is an independent project. It is not affiliated with, sponsored by, or endorsed by Spotify.
  13. > "Spotify" is a trademark of Spotify AB and is used here only to describe the API this tool works with.
  14. > Playback control needs Spotify Premium.
  15. ## Setup with an AI agent
  16. **For users:** give your AI agent (Codex, Claude, Cursor, Grok Bot, or similar) this repo URL and ask it to set it up:
  17. "Set this up: https://github.com/kenjitayama/dj-mcp". The agent can handle the rest except three steps that need you:
  18. 1. **Have Spotify Premium.** Playback control requires it.
  19. 2. **Create your own Spotify app** in the [Developer Dashboard](https://developer.spotify.com/dashboard), with Redirect URI
  20. `http://127.0.0.1:8888/callback` and **Web API** checked. Give the agent its Client ID. Each person or app uses its
  21. own Client ID, and no client secret is needed. Details: [1. Create a Spotify app](#1-create-a-spotify-app).
  22. 3. **Approve in the browser.** Open the link the agent shows you and click Agree. You'll land on a "can't connect" page,
  23. which is expected. Copy the **full URL** from the address bar and paste it back to the agent within a few minutes,
  24. before the code expires.
  25. **For agents**, step by step:
  26. 1. Check `node --version` is >= 20.
  27. 2. Run `git clone https://github.com/kenjitayama/dj-mcp /path/to/dj-mcp`. Below, `CLI` means `/path/to/dj-mcp/bin/dj-mcp`.
  28. 3. Save the user's Client ID, either as env `SPOTIFY_CLIENT_ID` or in `~/.config/dj-mcp/config.json`
  29. (folder 0700, file 0600). See [2. Set the Client ID](#2-set-the-client-id).
  30. 4. Run `CLI auth_start` and show the user the `authorize_url`.
  31. 5. Run `CLI auth_complete --redirect_url '<pasted URL>'`. Single-quote the URL, because it contains `&`.
  32. 6. Run `CLI auth_status` and confirm `authorized: true` and `missing_scopes: []`.
  33. 7. Run `CLI get_devices`. Devices only appear while a Spotify app is open, so if the list is empty, ask the user to open one.
  34. 8. With the user's OK, test playback: `CLI search --query '<song>'`, then `CLI transfer_playback --device_name '<name>'` and
  35. `CLI play --json '{"uris":["<track uri>"]}'`.
  36. 9. Register the MCP server (`node /path/to/dj-mcp/bin/dj-mcp-server`) with the user's client:
  37. - **Cursor / Claude Desktop:** see [Cursor](#cursor) and [Claude Desktop](#claude-desktop).
  38. - **Claude Code:** `claude mcp add --transport stdio --scope user dj-mcp -- node /path/to/dj-mcp/bin/dj-mcp-server`
  39. - **Codex:** `codex mcp add dj-mcp -- node /path/to/dj-mcp/bin/dj-mcp-server`, or in `~/.codex/config.toml`:
  40. ```toml
  41. [mcp_servers.dj-mcp]
  42. command = "node"
  43. args = ["/path/to/dj-mcp/bin/dj-mcp-server"]
  44. ```
  45. - **Anything else:** see [MCP: generic stdio](#mcp-generic-stdio).
  46. If the Client ID is in `config.json`, no env setting is needed in the client config.
  47. **Rules for agents:**
  48. - Never commit tokens or the Client ID to the repo, and never paste them into it.
  49. - Don't print tokens.
  50. - Don't ask for a client secret. It isn't needed.
  51. - Don't re-run `auth_start` while an authorization is pending, because it invalidates the earlier link.
  52. ## How this differs from other Spotify MCP servers
  53. There are several good Spotify MCP servers out there. This one makes a few particular choices that might suit some setups:
  54. - **Authorization Code + PKCE.** You only need your own app's Client ID. No client secret is stored or required.
  55. - **Zero runtime dependencies.** Plain Node.js (>= 20), with nothing to install from npm.
  56. - **A shell CLI on the same core** (`bin/dj-mcp`), for agents or scripts that can run commands but can't load MCP servers.
  57. - **`transfer_playback` (and other playback tools) accept a device name** as well as a device ID.
  58. - **Built for new Development Mode apps (February 2026 onward).** It avoids the endpoints that were removed or renamed for them.
  59. - **Small and playback-focused.** Search, devices, playback control, listening history, and simple playlist creation.
  60. If you're looking for more features, such as playlist editing or library management,
  61. [marcelmarais/spotify-mcp-server](https://github.com/marcelmarais/spotify-mcp-server) may be a better fit.
  62. ## 1. Create a Spotify app
  63. 1. Go to https://developer.spotify.com/dashboard and choose **Create app**. Spotify's guidelines say the app name must not
  64. include "Spotify" or anything similar to it (e.g. "My DJ Agent").
  65. 2. Set **Redirect URI** to exactly `http://127.0.0.1:8888/callback`. Nothing has to listen on that address,
  66. because you'll copy the redirected URL from the browser.
  67. 3. Under "Which API/SDKs are you planning to use?", check **Web API**. Save.
  68. 4. Copy the app's **Client ID**. It's public, not a secret. You don't need the client secret.
  69. 5. In development mode, only allowlisted users can authorize. Add your own Spotify account (and up to 4 others)
  70. under **User Management**.
  71. ## 2. Set the Client ID
  72. dj-mcp looks for the Client ID in this order (there is no built-in default):
  73. 1. the environment variable `SPOTIFY_CLIENT_ID`
  74. 2. `client_id` in `<config dir>/config.json`
  75. The config dir (which also holds the tokens) is `~/.config/dj-mcp`, or `DJ_MCP_CONFIG_DIR` if set.
  76. ```bash
  77. mkdir -p ~/.config/dj-mcp && chmod 700 ~/.config/dj-mcp
  78. printf '{\n "client_id": "YOUR_CLIENT_ID"\n}\n' > ~/.config/dj-mcp/config.json && chmod 600 ~/.config/dj-mcp/config.json
  79. ```
  80. If neither is set, tools return `client_id_missing` with these instructions.
  81. The refresh token is tied to the Client ID it was issued to, and refreshes always use the ID saved with the tokens.
  82. If you switch to a different app, run `auth_start` again. `auth_status` reports `client_id_mismatch` when the two differ.
  83. Optional: `SPOTIFY_REDIRECT_URI` if you registered a different loopback redirect.
  84. ## 3. Authorize (once per machine)
  85. 1. Call `auth_start` and open the `authorize_url` it returns in a browser signed in to Spotify. Click **Agree**.
  86. 2. The browser goes to `http://127.0.0.1:8888/callback?code=...&state=...` and shows a "can't connect" error.
  87. That's expected.
  88. 3. Copy the **full URL** from the address bar and call `auth_complete` with `redirect_url` set to it.
  89. It checks `state`. Do this soon after approving, because Spotify codes expire within minutes.
  90. Running `auth_start` again makes earlier URLs invalid.
  91. 4. `auth_status` should show `authorized: true` and `missing_scopes: []`.
  92. Requested scopes: `user-read-playback-state user-modify-playback-state user-read-currently-playing
  93. user-read-recently-played user-top-read playlist-read-private playlist-modify-private playlist-modify-public user-library-read`.
  94. ## 4. Use it
  95. ### CLI (any agent that can run shell commands)
  96. ```bash
  97. SDJ=/path/to/dj-mcp/bin/dj-mcp
  98. $SDJ tools # list tools and params
  99. $SDJ auth_status
  100. $SDJ auth_start
  101. $SDJ auth_complete --redirect_url 'http://127.0.0.1:8888/callback?code=...&state=...' # keep the single quotes
  102. $SDJ search --json '{"query":"artist:\"Bill Evans\" waltz","types":["track"],"limit":5}'
  103. $SDJ get_devices
  104. $SDJ transfer_playback --device_name 'Living Room' --play false
  105. $SDJ play --json '{"uris":["spotify:track:..."]}'
  106. $SDJ play --json '{"context_uri":"spotify:album:...","offset":0}'
  107. $SDJ set_volume --volume_percent 40
  108. $SDJ get_currently_playing
  109. ```
  110. You can pass arguments as `--json '{...}'`, as a bare JSON object, or as `--key value`. Values are JSON-parsed,
  111. except string fields like URLs and IDs. Output is JSON. On failure it prints
  112. `{"error":{"code","message","hint"?,"status"?,"retry_after"?}}` and exits with code 1.
  113. Error codes worth handling: `client_id_missing`, `not_authorized`, `invalid_grant` (re-authorize), `no_active_device`,
  114. `device_not_found`, `rate_limited`, `forbidden`, `premium_required`, `state_mismatch`.
  115. ### MCP: generic stdio
  116. The server speaks newline-delimited JSON-RPC 2.0 on stdio: `node /path/to/dj-mcp/bin/dj-mcp-server`.
  117. ### Claude Desktop
  118. `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/`, Windows: `%APPDATA%\Claude\`):
  119. ```json
  120. {
  121. "mcpServers": {
  122. "dj-mcp": {
  123. "command": "node",
  124. "args": ["/ABSOLUTE/PATH/dj-mcp/bin/dj-mcp-server"],
  125. "env": { "SPOTIFY_CLIENT_ID": "YOUR_CLIENT_ID" }
  126. }
  127. }
  128. }
  129. ```
  130. If `node` isn't found, use its absolute path (`which node`).
  131. ### Cursor
  132. Option A, as a local plugin: copy the folder itself (not a symlink) to `~/.cursor/plugins/local/dj-mcp` and reload.
  133. Cursor doesn't expand the standard `${PLUGIN_ROOT}` placeholder used in `mcp.json`'s `cwd`. The server doesn't depend
  134. on its working directory, but if it won't start that way, use option B.
  135. Option B, as a plain MCP server in `~/.cursor/mcp.json` (or `.cursor/mcp.json` in a project):
  136. ```json
  137. {
  138. "mcpServers": {
  139. "dj-mcp": {
  140. "command": "node",
  141. "args": ["/ABSOLUTE/PATH/dj-mcp/bin/dj-mcp-server"],
  142. "env": { "SPOTIFY_CLIENT_ID": "YOUR_CLIENT_ID" }
  143. }
  144. }
  145. }
  146. ```
  147. ### Other Agent Plugins clients
  148. Install the directory as a plugin. `mcp.json` declares a stdio server (`./bin/dj-mcp-server`) and
  149. `skills/dj-mcp/SKILL.md` tells the agent when to call each tool.
  150. `SPOTIFY_CLIENT_ID` is declared under `extensions["com.cursor"].variables`, because the Agent Plugins manifest
  151. schema has no top-level `variables` key. An unexpanded `${SPOTIFY_CLIENT_ID}` placeholder counts as unset.
  152. ## Tools
  153. | tool | purpose |
  154. |---|---|
  155. | auth_start | Create and save a PKCE verifier and state; return `authorize_url` |
  156. | auth_complete | Take `redirect_url` (state checked) or a bare `code`; exchange it and store tokens |
  157. | auth_status | Authorized or not, expiry, granted/missing scopes, Client ID source (never tokens) |
  158. | search | track/album/artist/playlist; `limit` forced into 1..10 (default 5); page with `offset` |
  159. | get_devices | Spotify Connect devices → `Device[]` |
  160. | transfer_playback | Make a device active (`device_id` or `device_name`, optional `play`) |
  161. | play | `uris[]`, or `context_uri` (+ `offset` index or URI), `position_ms`, device; no args = resume |
  162. | pause / next / previous | Playback controls (optional device) |
  163. | set_volume | 0–100 |
  164. | add_to_queue | Add a track/episode URI to the queue |
  165. | get_currently_playing | `Playback` |
  166. | get_recently_played | `[{played_at, track}]` (limit ≤50, `before`/`after` cursors) |
  167. | get_top_items | Top tracks or artists, `time_range` short/medium/long_term |
  168. | create_playlist | `POST /me/playlists` (private by default) |
  169. | add_items_to_playlist | `POST /playlists/{id}/items`, in batches of 100 |
  170. URIs can also be `open.spotify.com/...` links.
  171. ## Shapes
  172. `Track {uri,name,artists[],album,duration_ms}` · `Device {id,name,type,is_active,volume_percent}` ·
  173. `Playback {device,item,is_playing,progress_ms,shuffle,repeat}` · `Album {uri,name,artists[],release_date,total_tracks}` ·
  174. `Artist {uri,name,genres[]}` · `Playlist {uri,id,name,owner,public,total_items,description}`.
  175. ## Spotify development-mode limits
  176. Checked against developer.spotify.com in November 2026: the February 2026 Web API changelog and migration guide,
  177. the March 2026 changelog, and the November 2024 Web API announcement.
  178. - The app owner needs an active **Premium** subscription. A development-mode app allows at most **5 users**,
  179. and they must be allowlisted.
  180. - `GET /search`: `limit` max is **10** (default 5). Page with `offset`.
  181. - Playlist items: `/playlists/{id}/tracks` → `/playlists/{id}/items`. Contents are returned only for playlists the
  182. user owns or collaborates on, and the `tracks` field is renamed `items`.
  183. - Create playlist: `POST /me/playlists` (`POST /users/{id}/playlists` was removed).
  184. - Library: save/remove/follow → `PUT/DELETE /me/library` (URIs); contains checks → `GET /me/library/contains`.
  185. - Removed: batch GETs (`/tracks`, `/albums`, `/artists`, ...), artist top tracks, new releases, browse categories,
  186. other users' profiles and playlists, markets. `popularity` and some other fields were removed from objects.
  187. - Unavailable to development-mode apps since 2024-11-27: recommendations, related artists, audio features,
  188. audio analysis, featured playlists, category playlists, and 30-second preview URLs.
  189. The agent has to choose tracks itself from search, top items and recent plays.
  190. ## Development
  191. ```bash
  192. npm test # node --test, no network: fetch is mocked; the stdio smoke test spawns the real server with a fake Client ID
  193. ```
  194. See `VERIFY.md` for the verification checklist.
  195. ## License
  196. MIT. See `LICENSE`.

Version history

  • v0.2.011/22/2026

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.