JamRelay

Self-hosted music automation for AI agents through MCP.

Documentation · Quick start · Polski

What is JamRelay?

JamRelay connects compatible AI assistants to your music services. Search for music, organize playlists and run repeatable music workflows through one MCP server that you host and control.

It supports Spotify, SoundCloud, Apple Music and YouTube. Each provider keeps its own connection and capabilities; an installation can start without any connected accounts.

Key features

• Music workflows: search, playlist organization, transfers and automation.
• Preview before writing: dry runs, snapshots and recovery information for supported playlist operations.
• Durable jobs: long-running work with progress, cancellation and recovery.
• Owner-controlled access: explicit provider authorization and MCP grants.
• Local operation: persistent state, encrypted provider credentials and an operator CLI, with no web administration dashboard.

See the guides and provider capabilities for supported operations and their limits.

Quick start

Requires Node.js 22.13 or later. Once the official npm package is published:

npm install -g jamrelay
jamrelay setup
jamrelay start
jamrelay onboard

The setup command configures storage and a masked owner password, then exits. Run jamrelay onboard to configure network access, music connections and MCP clients or open the management menu. You obtain provider developer credentials yourself and authorize accounts separately through the owner consent flow. Existing installations can stop the server and run jamrelay owner password without changing encryption keys.

Public distribution is pending. For a development checkout or candidate archive, follow installation. The same page covers the recommended Docker Compose workflow and persistent storage.

Supported providers

Provider	Integration
Spotify	Catalog, playlists, library and supported playback controls
SoundCloud	Catalog and playlists
Apple Music	Catalog and supported MusicKit library playlist operations
YouTube	Videos and playlists through YouTube Data API v3

Features differ by provider. See provider setup for credentials, authorization and capability restrictions. Spotify playback requires an eligible account and active device.

Connect your AI agent

Add the MCP endpoint shown by setup to a compatible client, complete owner OAuth consent, then request its tool list to verify the connection. jamrelay connect client claude-code can register a local Claude Code installation after confirmation; inside Docker it prints the exact host-side command. Use --verify afterward to check actual OAuth authentication and tool discovery. The local default is http://localhost:5267/mcp; remote access requires reachable HTTPS.

ChatGPT · Claude · Cursor · Other MCP clients

Documentation

• Install and deploy
• Connect music providers
• Connect an AI client
• CLI updates, notices and offline information
• Operations and backups
• Generated MCP tool reference
• Security

Provider integrations require individual credentials and authorization; live verification is separate from automated tests. See the release review notes.

English is canonical. Entry points are available in Polski, Deutsch, Français and Español; incomplete translations link to English references.

For release history, see CHANGELOG and GitHub Releases.

Contributing & license

Read CONTRIBUTING before submitting changes and SECURITY to report a vulnerability.

JamRelay is licensed under AGPL-3.0-only; see licensing for additional information.

This is an unofficial community project, unaffiliated with music providers or AI platform vendors. Provider terms and API limitations still apply.

Manage MCP permissions

Permissions belong to authenticated OAuth registrations, independently of the model or application name. New approvals default to read-only and require explicit account selection. Existing grants, credentials and database migrations are preserved.

jamrelay clients list
jamrelay clients show CLIENT_ID
jamrelay clients permissions CLIENT_ID
jamrelay clients permissions set CLIENT_ID
jamrelay clients permissions set CLIENT_ID --permissions catalog.read,playlist.read --connections spotify-default --tools all
jamrelay clients revoke CLIENT_ID
jamrelay clients policy
jamrelay clients policy set --permissions catalog.read,playlist.read,diagnostics.read --tools all

permissions set opens an interactive selector without flags; --tools can restrict a grant to comma-separated tool names. Empty scope/account/tool lists deny access. Policy changes alter initial consent defaults only; existing grants remain unchanged. Grant changes apply to existing tokens and queued work immediately. Refresh the client's tool list after editing; revoked OAuth clients must authorize again. An external provider request already accepted cannot be recalled. Legacy API-key access remains an owner-controlled shared registration named api-key; use OAuth for separate client identities.

New installations default to JAMRELAY_TOOLSET=essential (14 common tools before permission/capability filtering). advanced adds music automation, transfer and personalization; all also exposes authorized internal diagnostics. Existing configured profiles are retained. Version 1.5.7 retires 20 nonfunctional/obsolete tool registrations; the full catalog has 95 tools with database features enabled. Provider support and grants can reduce discovery further.

jamrelay connect client cursor and jamrelay connect client vscode offer project/user configuration with JSONC preservation and backups. Different existing JamRelay entries are preserved for manual review. Claude Code registration uses its installed CLI; Claude Desktop can use the optional local stdio bridge described in the client guide. Containers print instructions for the host (PowerShell on Windows). OAuth login, observed tool discovery and provider authorization remain separate verification steps. Spotify and native Windows Docker/Desktop flows require the owner's live test.