JamRelay

Self-hosted MCP server for connecting AI assistants to your own Spotify account.

Unofficial project: JamRelay is not affiliated with, endorsed by, or sponsored by Spotify, OpenAI, Anthropic, Google, or any other AI platform vendor.

JamRelay exposes Spotify search, playlist, library, discovery and playback tools over MCP Streamable HTTP. It supports Spotify OAuth, multi-client MCP OAuth with PKCE, Dynamic Client Registration (DCR), optional static Bearer authentication, encrypted token persistence, a persistent SQLite State DB, and Docker deployment.

Documentation

The VitePress documentation is the primary user documentation:

• English — canonical / source of truth

• Polski — high-priority translation

• Deutsch — best effort

• Français — best effort

• Español — best effort

Translations may lag behind the English documentation. The website displays that warning automatically on non-English pages. See the translation policy.

Related MCP server: Spotify MCP Server

Quick start

npm ci
cp .env.example .env
npm run dev

PowerShell:

Copy-Item .env.example .env
npm run dev

Configure your own Spotify Developer application and secrets in .env, then open /auth/spotify/login.

MCP OAuth compatibility

One deployment can keep an existing pre-registered ChatGPT client while also accepting DCR clients such as Claude Code, Gemini CLI, VS Code, and other standards-compatible MCP hosts. ChatGPT has been exercised end-to-end on the project deployment; other vendor paths are documented as protocol-compatible until separately verified. See OAuth and multi-client compatibility.

Common deployment paths

• local Node.js

• Docker / Docker Compose

• home server or NAS

• local machine + Cloudflare Tunnel

• free-tier VM with persistent storage

• small paid VPS

See free hosting and free/low-cost deployment.

The State DB architecture, schema, migration policy, backup guidance, and security boundary are documented in State Database.

Create reviewed local migrations with npm run db:migration:new -- add-track-isrc; deployment never generates schema changes.

Documentation maintenance

Fast-changing technical references are generated instead of copied across five locales:

npm run docs:generate

This regenerates:

• MCP tool reference from the actual registered MCP tools

• environment variable reference from .env.example

• translated reference stubs that point to the canonical generated reference

Navigation is defined once in docs/.vitepress/navigation.mts. Add a page there once; localized labels are optional and fall back to English.

Run the full documentation validation with:

npm run docs:check

Development

npm run format
npm run lint
npm run typecheck
npm test
npm run build
npm run docs:build

Or run the combined verification:

npm run check

Security

See SECURITY.md. Keep .env, OAuth token stores and /data out of version control and public web roots.

License

JamRelay is licensed under the GNU Affero General Public License v3.0 only (AGPL-3.0-only).

See LICENSE for the complete license text and LICENSING.md for licensing history and additional information.