{"_id":"mcp-spotify-free","_rev":"4-32c4696e93cb3a5d0a0a9f645e730650","name":"mcp-spotify-free","dist-tags":{"latest":"1.1.2"},"versions":{"0.0.0-stage":{"name":"mcp-spotify-free","version":"0.0.0-stage","_id":"mcp-spotify-free@0.0.0-stage","stub":true,"maintainers":[{"name":"vakandi","email":"wael.bousfira@gmail.com"}],"dist":{"shasum":"c4b819879690bf7b38db2286ed06a002babee99d","tarball":"https://registry.npmjs.org/mcp-spotify-free/-/mcp-spotify-free-0.0.0-stage.tgz","fileCount":2,"integrity":"sha512-2hLDjtvqzJsmHTSQNXEEmvxYHYNmlM7j61LpOzcj9XhV4thEy8KdDiDFZKu7mv9itsJWt/X/yDaV5anx+hJ0IQ==","signatures":[{"sig":"MEYCIQDXXxUCty0YpRtG01nRGuw3HOVpR5/syEkrPz4r+2mmRQIhAI0XA2YTXuhMun0yxR889qQevL6jqMn2NTpa/PkM/all","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":338},"_npmUser":{"name":"vakandi","email":"wael.bousfira@gmail.com"},"description":"Temporary package placeholder for staged publishing","directories":{}},"1.1.0":{"name":"mcp-spotify-free","version":"1.1.0","keywords":["mcp","model-context-protocol","npx","claude-desktop","cursor","spotify","spotify-free","liked-songs","chromecast","spotify-connect","macos"],"author":{"name":"Wael Bousfira"},"license":"MIT","_id":"mcp-spotify-free@1.1.0","maintainers":[{"name":"vakandi","email":"wael.bousfira@gmail.com"}],"bin":{"mcp-spotify-free":"bin/mcp-spotify-free"},"dist":{"shasum":"01b82365421245f93de9ce903021c4a7633ec24d","tarball":"https://registry.npmjs.org/mcp-spotify-free/-/mcp-spotify-free-1.1.0.tgz","fileCount":13,"integrity":"sha512-c23Lobp9PZW5CjTCV3Ac0bIAREFWhEjvckxmZfqy6Ng5z/iSERWptacpEKohj7ixHWuSWTBstCTOqCg2EF3pYQ==","signatures":[{"sig":"MEQCIDPF1RCGXSLeigCf9RyhzojJkcRnHG4XRGk9MuxihM+XAiA1Btx5P0Stmfggv8Ex0Z+QiUWZ3Gj3gSDkJvHMddOIVA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEUCIQD0NwirW7rCRMjhDtmU5DZrmTkh0pVyfOLXRUozPlxONwIgNU8+F8ezsmwIFEIYd/Qk/lwQvzJmjAfuN98ucV0eCms=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":106465},"engines":{"node":">=18"},"scripts":{"postinstall":"node postinstall.js"},"_npmUser":{"name":"vakandi","email":"wael.bousfira@gmail.com"},"_npmVersion":"11.21.0","description":"MCP server for Spotify FREE accounts: read your Liked Songs library and control playback on any Spotify Connect device (Chromecast, MacBook, TV) - no Premium required","directories":{},"_nodeVersion":"20.20.2","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/mcp-spotify-free_1.1.0_1792682533243_0.5523595501634482","host":"s3://npm-registry-packages-npm-production"}},"1.1.1":{"name":"mcp-spotify-free","version":"1.1.1","keywords":["mcp","model-context-protocol","npx","claude-desktop","cursor","spotify","spotify-free","liked-songs","chromecast","spotify-connect","macos"],"author":{"name":"Wael Bousfira"},"license":"MIT","_id":"mcp-spotify-free@1.1.1","maintainers":[{"name":"vakandi","email":"wael.bousfira@gmail.com"}],"homepage":"https://github.com/vakandi/mcp-spotify-free#readme","bugs":{"url":"https://github.com/vakandi/mcp-spotify-free/issues"},"bin":{"mcp-spotify-free":"bin/mcp-spotify-free"},"dist":{"shasum":"6f3e36bcca9632c5445a8adf825ab685e7f16d39","tarball":"https://registry.npmjs.org/mcp-spotify-free/-/mcp-spotify-free-1.1.1.tgz","fileCount":13,"integrity":"sha512-ZAZv9UFlYAKVnyXcqjrbiHQl4cv6AlUxNUOZ3jc0OJRow7j7aESSSJRygJthdSWPphijnS090kfPR4fU0mDN+g==","signatures":[{"sig":"MEUCIEPTmRplyR9ql72zeP+AfpUvqcCFMjdwUZjJVL1HYh+IAiEA+TsaP+DfB6TegwXrEbxRO5lbXuRGPQ2cTpqBhbTDSYU=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEUCIQDmM2VymLy8t9ykmS/+8S7270EnIrSvy+He6QVWKIXXngIgfuuz9w+f6WjCHcagZwFqPo9AqLvuxGr1rGT/xO8fmhQ=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":106721},"engines":{"node":">=18"},"gitHead":"8a157de53fb864593a4a34fbcf08a62b7654daef","scripts":{"postinstall":"node postinstall.js"},"_npmUser":{"name":"vakandi","email":"wael.bousfira@gmail.com"},"repository":{"url":"git+https://github.com/vakandi/mcp-spotify-free.git","type":"git"},"_npmVersion":"11.21.0","description":"MCP server for Spotify FREE accounts: read your Liked Songs library and control playback on any Spotify Connect device (Chromecast, MacBook, TV) - no Premium required","directories":{},"_nodeVersion":"20.20.2","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/mcp-spotify-free_1.1.1_1792682676379_0.3161955622240318","host":"s3://npm-registry-packages-npm-production"}},"1.1.2":{"_id":"mcp-spotify-free@1.1.2","bin":{"mcp-spotify-free":"bin/mcp-spotify-free"},"bugs":{"url":"https://github.com/vakandi/mcp-spotify-free/issues"},"dist":{"shasum":"5cd097aea0b3f0963ef8903ee86925c792a39778","tarball":"https://registry.npmjs.org/mcp-spotify-free/-/mcp-spotify-free-1.1.2.tgz","fileCount":15,"integrity":"sha512-MhU2AglSIeLzUJxQX+VFltZzA9mLe4XxLUdbDJ0G1ryrvabB2H+RRVfPPi8FYTZT7B48hIwN4VNYosaE109iwg==","signatures":[{"sig":"MEUCIQCzgZHuqRDEL81OMt6e89R9VDsgmkeZ36smH84muiI2lgIgX4/kaCMrwp8Pb5Lg6y50WMfU0h6fMqU5citSGb8wQJk=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQD/q63HH1p1KidwcK2w0yTx8kvhZUpxQbKBor7IFzGX8AIgTzjIZUemdabzPlZE73VvFDgWi4NCZjRyP7687znc0gk="}],"unpackedSize":323447},"name":"mcp-spotify-free","author":{"name":"Wael Bousfira"},"engines":{"node":">=18"},"gitHead":"9311581903f986beda8932f48f463254e6f4149c","license":"MIT","scripts":{"postinstall":"node postinstall.js"},"version":"1.1.2","_npmUser":{"name":"vakandi","email":"wael.bousfira@gmail.com"},"homepage":"https://github.com/vakandi/mcp-spotify-free#readme","keywords":["mcp","model-context-protocol","npx","claude-desktop","cursor","spotify","spotify-free","liked-songs","chromecast","spotify-connect","macos"],"repository":{"url":"git+https://github.com/vakandi/mcp-spotify-free.git","type":"git"},"_npmVersion":"11.21.0","description":"MCP server for Spotify FREE accounts: read your Liked Songs library and control playback on any Spotify Connect device (Chromecast, MacBook, TV) - no Premium required","directories":{},"maintainers":[{"name":"vakandi","email":"wael.bousfira@gmail.com"}],"_nodeVersion":"20.20.2","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp-spotify-free_1.1.2_1793902923591_0.07085421874421971"}}},"time":{"created":"2026-10-22T15:20:04.860Z","modified":"2026-11-05T18:22:03.897Z","0.0.0-stage":"2026-10-22T15:20:04.860Z","1.1.0":"2026-10-22T15:22:13.335Z","1.1.1":"2026-10-22T15:24:36.478Z","1.1.2":"2026-11-05T18:22:03.738Z"},"bugs":{"url":"https://github.com/vakandi/mcp-spotify-free/issues"},"author":{"name":"Wael Bousfira"},"license":"MIT","homepage":"https://github.com/vakandi/mcp-spotify-free#readme","keywords":["mcp","model-context-protocol","npx","claude-desktop","cursor","spotify","spotify-free","liked-songs","chromecast","spotify-connect","macos"],"repository":{"url":"git+https://github.com/vakandi/mcp-spotify-free.git","type":"git"},"description":"MCP server for Spotify FREE accounts: read your Liked Songs library and control playback on any Spotify Connect device (Chromecast, MacBook, TV) - no Premium required","maintainers":[{"name":"vakandi","email":"wael.bousfira@gmail.com"}],"readme":"<!-- Banner -->\n<p align=\"center\">\n  <img src=\"./.assets/banner.png\" alt=\"mcp-spotify-free — Spotify for free accounts\" width=\"100%\">\n</p>\n\n<!-- Tagline -->\n<p align=\"center\">\n  <strong>Spotify for free accounts — as an MCP server.</strong><br>\n  Read your <em>Liked Songs</em>, search the whole catalog, and drive playback on\n  <strong>any</strong> Spotify Connect device (Chromecast, TV, phone, desktop). No Premium.\n</p>\n\n<!-- Badges -->\n<p align=\"center\">\n  <a href=\"https://github.com/vakandi/mcp-spotify-free\"><img src=\"https://img.shields.io/badge/version-1.1.2-8B5CF6?style=flat-square\" alt=\"Version\"></a>\n  <a href=\"https://www.npmjs.com/package/mcp-spotify-free\"><img src=\"https://img.shields.io/npm/v/mcp-spotify-free?style=flat-square&color=3B82F6\" alt=\"npm\"></a>\n  <a href=\"https://github.com/vakandi/mcp-spotify-free/blob/main/LICENSE\"><img src=\"https://img.shields.io/badge/license-MIT-22C55E?style=flat-square\" alt=\"License\"></a>\n  <a href=\"https://github.com/vakandi/mcp-spotify-free\"><img src=\"https://img.shields.io/badge/python-3.10+-3B82F6?style=flat-square\" alt=\"Python\"></a>\n  <a href=\"https://github.com/vakandi/mcp-spotify-free\"><img src=\"https://img.shields.io/badge/platform-macOS-64748B?style=flat-square\" alt=\"Platform\"></a>\n  <a href=\"https://github.com/vakandi/mcp-spotify-free\"><img src=\"https://img.shields.io/badge/PRs-welcome-EC4899?style=flat-square\" alt=\"PRs Welcome\"></a>\n</p>\n\n---\n\n## Why this exists\n\nSpotify's public Web API hides the *Liked Songs* playlist behind Premium:\n`GET /v1/me/tracks` answers **403** on a free account, and so does every\nlibrary-read endpoint built on it. Almost every \"Spotify liked songs exporter\"\non GitHub uses `spotipy.current_user_saved_tracks()` — Premium only.\n\nThe Spotify **web player** has no such restriction: it serves the full library\nto free users. This server speaks the same internal protocol the web player\nuses, so a free account gets:\n\n- its complete *Liked Songs* playlist (591 tracks on the reference account)\n- **catalog search** — the same search box as the web player (tracks, artists,\n  albums, playlists, profiles), so any song can be played, not only the liked ones\n- real playback control — play, pause, skip, volume\n- **device switching** — send the sound to the Chromecast instead of the laptop\n\n### Every other Spotify MCP server needs Premium (checked October 2026)\n\nA sweep of the MCP registries and PyPI/GitHub found no other Spotify MCP\nserver that works on a plain free account. They all go through the official\nSpotify Web API, which means a registered developer app + OAuth, and playback\nis Premium-only — before Spotify tightened the API in February 2026, where the\napp **owner must now hold Premium** and Dev Mode apps are capped at 5\nauthorized users. For example, quoting their own docs:\n\n- `marcelmarais/spotify-mcp-server` — prerequisites: \"A Spotify Premium\n  account\" + \"A registered Spotify Developer application\"\n- `mcp-spotify` (PyPI) — \"A Spotify Premium account (required by Spotify for\n  Web API access)\"\n- `jamiew/spotify-mcp` — \"Requires a Spotify Premium account\"\n- `mcp-server-spotify` (PyPI) / `leoalord/spotify-mcp-server` /\n  `iceener/spotify-streamable-mcp-server` — bring your own developer app\n  (client ID + secret + OAuth), Premium required for playback since Feb 2026\n\nThis server needs none of that: no developer app, no OAuth callback, no\nclient secret, no Premium. It reads the session cookies of a browser where\nyou are already logged in and speaks the web player's own protocol.\n\n---\n\n## Quick Start\n\n### npx (recommended)\n\n```bash\nnpx mcp-spotify-free\n```\n\n### npm install (global)\n\n```bash\nnpm install -g mcp-spotify-free\nmcp-spotify-free\n```\n\n### From source\n\n```bash\ncd ~/Documents/mcp-spotify-free\npython3 -m pip install -r requirements.txt\npython3 server.py login\n```\n\n---\n\n## How it works\n\n**1. Session (no password, no OAuth app, no Premium)**\nThe server reads the Spotify cookies of a browser where you are already logged\nin (`open.spotify.com`), decrypts them locally with the macOS keychain\n(`PBKDF2-HMAC-SHA1` + `AES-128-CBC`, the standard Chromium scheme), and\nexchanges them for a short-lived user access token.\n\nTwo sources are tried, in order:\n- `~/.config/mcp-spotify-free/cookies.json` — the captured session (works\n  with the browser closed)\n- the browser profile itself (Edge by default) — read straight from the\n  Chromium cookie database, nothing is dumped or copied out\n\n`spotify_session_status()` tells you which one is in use and whether Spotify\nstill accepts it.\n\n**2. TOTP guard**\n`open.spotify.com/api/token` is protected by a 6-digit TOTP\n(HMAC-SHA1, 30 s period) whose secret is XOR-obfuscated inside the web-player\nbundle. `spotify_free/totp.py` de-obfuscates it, re-reads the live bundle on\nevery run (the file name changes with every Spotify release — the current one\nis looked up in the `open.spotify.com` HTML), and keeps a hardcoded fallback\nso a network hiccup never breaks the server.\n\n**3. Library**\n`POST api-partner.spotify.com/pathfinder/v2/query` — the same GraphQL-ish\ngateway the web player uses — with the `fetchPlaylistContents` operation and\nthe *Liked Songs* playlist alias `spotify:playlist:37i9dQZF1F5p3rmiWPIYgZ`\n(also hardcoded in the web player, not account specific).\n\n**4. Catalog search**\nSame gateway, `searchTopResultsList` operation — the endpoint behind the\nweb player's search box. It works on a free account.\n\n**5. Playback**\nThe Spotify Connect \"harmony\" command protocol:\n\n```\nPOST connect-state/v1/player/command/from/{source}/to/{target}\nPUT  connect-state/v1/connect/volume/from/{source}/to/{target}\n```\n\nAddressing the command to the Chromecast's device id *is* the \"play on\" — the\naudio moves from the laptop to the TV.\n\n**Device policy — the server leaves no trace**\nThe command protocol needs a *source* device. Registering one would add a\npermanent entry (\"MCP Spotify Free\") to the account's device list, and every\ncrashed run would leave another ghost behind. Instead the server **reuses the\naccount's own web-player device** (`Web Player (Microsoft Edge)`) as the\nsource: the commands are accepted exactly the same way, and nothing is added\nto the device list. Only if no web-player device exists does the server\nregister one — with a **stable, persisted device id**, so even then the list\nnever grows beyond a single entry.\n\n`cleanup_devices()` removes the entries left by earlier versions. It uses\n`DELETE /connect-state/v1/devices/{id}`, which drops the entry from the\naccount's device list immediately (the `hobs_` variant only drops the\nsubscription and leaves a visible ghost for hours).\n\n---\n\n## IDE Integration\n\n### Cursor / Windsurf / VS Code\n\n```json\n{\n  \"mcpServers\": {\n    \"spotify-free\": {\n      \"command\": \"npx\",\n      \"args\": [\"mcp-spotify-free\"]\n    }\n  }\n}\n```\n\n### Claude Desktop\n\n```json\n{\n  \"mcpServers\": {\n    \"spotify-free\": {\n      \"command\": \"npx\",\n      \"args\": [\"mcp-spotify-free\"]\n    }\n  }\n}\n```\n\n### OpenCode / Claude Code\n\n```bash\nclaude mcp add spotify-free --scope user -- npx mcp-spotify-free\n```\n\n### Through `mcp-cli` (this machine)\n\nThe server is registered in `~/.config/mcp/mcp_servers.json` under\n`spotify-free`, so it is reachable through the `mcp-cli` wrapper:\n\n```bash\nmcp-cli info spotify-free                                  # list the tools\nmcp-cli call spotify-free spotify_status '{}'               # account + devices\nmcp-cli call spotify-free play_song '{\"query\":\"one more time\",\"device\":\"Chromecast\"}'\nmcp-cli call spotify-free cleanup_devices '{}'              # drop leftover devices\n```\n\n---\n\n## Tools\n\n- **`get_docs()`** — the full usage guide, returned as one big text. Start here.\n- **`spotify_status()`** — account, token state, liked-song count, now playing,\n  every Connect device.\n- **`list_liked_songs(limit, offset, query)`** — the Liked Songs playlist,\n  newest first. With `query` the whole library is scanned.\n- **`search_liked_songs(query, limit)`** — only the matches, whole library.\n- **`search_spotify(query, limit)`** — the **whole catalog**: tracks, artists,\n  albums, playlists, profiles.\n- **`play_song(query, device, index)`** — *the main one*: looks the title up in\n  the Liked Songs, falls back to the catalog, and plays the best match.\n  `source` in the answer tells you where the match came from.\n- **`play_liked_song(query, device, index)`** — Liked Songs only.\n- **`play_track(uri, device)`** — play a raw `spotify:track:...` URI.\n- **`chromecast_sent(track_query, action)`** — the shortcut: always the\n  Chromecast. `action` = `play` / `resume` / `pause` / `next` / `previous`.\n- **`pause_playback(device)`** / **`resume_playback(device)`**\n- **`skip_next(device)`** / **`skip_previous(device)`**\n- **`set_volume(level, device)`** — 0-100.\n- **`list_devices()`** — every Connect device with its volume and active flag.\n- **`now_playing()`** — current track, playing/paused, position, active device.\n- **`cleanup_devices()`** — remove the leftover `MCP Spotify Free` Connect\n  devices of the earlier versions.\n- **`spotify_session_status()`** — diagnose the session.\n- **`spotify_login()`** / **`spotify_logout()`** — capture / forget the session.\n\nEvery tool returns a structured payload: `ok`, `action`, plus the relevant\ndata — and on failure `error` with a human-readable cause. When the failure is\nthe session (bad or expired browser cookies, `401` / `403` from the token\nendpoints), the payload also carries a `remedy` block with paste-ready\ncommands for the agent: show a macOS popup explaining the login is needed,\nopen `https://open.spotify.com` in the default browser, run\n`spotify_login()`, then retry the original call.\n\n### Typical agent flow\n\n```\nget_docs()\n  -> list_devices()                      # find the Chromecast\n  -> play_song(\"one more time\", \"Chromecast\")   # library first, catalog fallback\n  -> pause_playback()\n```\n\n---\n\n## Direct use from Python\n\n```python\nfrom spotify_free import SpotifyFreeClient\n\nclient = SpotifyFreeClient()\n\nfor track in client.liked_songs(limit=5):\n    print(track[\"name\"], \"-\", \", \".join(track[\"artists\"]), \"|\", track[\"added_at\"])\n\nhits = client.search_catalog(\"le songe\")       # the whole catalog\nclient.play_track(hits[\"tracks\"][0][\"uri\"], device=\"Chromecast\")\nclient.pause()\n```\n\nOr run the bundled demo:\n\n```bash\npython3 examples/quickstart.py\n```\n\n---\n\n## Requirements\n\n| Item | Detail |\n|------|--------|\n| OS | macOS (cookie decryption uses the login keychain) |\n| Browser | Edge by default; Chrome, Brave, Vivaldi, Opera supported — must have an active `open.spotify.com` session |\n| Python | 3.10+ |\n\nEnvironment variables:\n\n- `SPOTIFY_BROWSER` — `edge` (default), `chrome`, `brave`, `vivaldi`, `opera`\n- `SPOTIFY_COOKIES_FILE` — path to a JSON file of cookies (bypasses the browser)\n- `SPOTIFY_USE_PROXY` — set to `1` to send traffic through the system proxy\n  (off by default: the local `proxy-local` plugin only carries LLM traffic)\n\n---\n\n## Architecture\n\n```\nmcp-spotify-free/\n├── server.py               FastMCP server + all tool definitions\n├── spotify_free/\n│   ├── client.py           token, library, catalog search, devices, playback\n│   ├── cookies.py          Chromium cookie decryption (macOS keychain)\n│   ├── session.py          session capture / storage / validation\n│   └── totp.py             web-player TOTP (de-obfuscation + auto-discovery)\n├── examples/quickstart.py  dependency-free demo\n├── requirements.txt\n└── pyproject.toml\n```\n\n---\n\n## Privacy & terms\n\n- Cookies are read from your own machine and decrypted locally. They are never\n  written to disk (except the captured copy in\n  `~/.config/mcp-spotify-free/cookies.json`, mode 0600) and never sent\n  anywhere but Spotify.\n- No password is ever handled, and no Spotify developer app / client secret is\n  involved.\n- The access token lives in memory for the lifetime of the process.\n- **Spotify's Developer Terms do not allow third-party use of the web-player\n  token endpoint.** This is a personal tool for your own account — do not ship\n  it as a product or redistribute it.\n\n---\n\n## Troubleshooting\n\n- **Any session/cookie failure (`401`, `403`, `no spotify cookies found`)** —\n  the failing tool returns a `remedy` field instead of a dead error: it tells\n  the calling agent to show the user a macOS popup (\"log in so music can play\"),\n  to open `open.spotify.com` in the default browser, to `spotify_login()` and\n  retry. Nothing else to do by hand.\n- **`no spotify cookies found`** — log in to `open.spotify.com` in the browser\n  named by `SPOTIFY_BROWSER`, then retry.\n- **`token request failed (400)`** — the TOTP version moved on; the server\n  re-reads the bundle automatically, but check that `open.spotify.com` is\n  reachable.\n- **`no active Spotify device`** — start the Spotify app (or any Connect\n  device) so the account has an active player.\n- **`no device matching 'x'`** — call `list_devices()` for the exact names.\n- **A \"MCP Spotify Free\" entry shows up in the Spotify app** — run\n  `cleanup_devices()`; it removes the entry from the account's device list.\n- **Keychain prompt on first run** — macOS asks once to let `security` read the\n  browser's *Safe Storage* item.\n\n---\n\n## Contributing\n\nPRs welcome. Open an issue first for non-trivial changes.\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n","readmeFilename":"README.md"}