Tempo

Spotify control + lyrics - Playback control, queue management, synced lyrics via MCP.

Keep the rhythm going.

Deployment

Deploy to your own Cloudflare Workers account. Version: 2.0.0

Endpoints

Endpoint	Description
`/health`	Health check + Spotify status
`/auth`	Spotify OAuth flow
`/callback`	OAuth callback
`/sse`	MCP via Server-Sent Events
`/mcp`	Standard MCP endpoint

Tools

Spotify Playback

Tool	Description
`spotify_now_playing`	Get currently playing track
`spotify_play`	Start/resume playback
`spotify_pause`	Pause playback
`spotify_next`	Skip to next track
`spotify_previous`	Go to previous track
`spotify_volume`	Set volume (0-100)
`spotify_shuffle`	Toggle shuffle
`spotify_repeat`	Set repeat mode
`spotify_search`	Search tracks/albums/artists/playlists
`spotify_queue`	Add track to queue
`spotify_get_queue`	View current queue
`spotify_devices`	List available devices
`spotify_transfer`	Transfer playback to device
`spotify_playlists`	Get user playlists
`spotify_create_playlist`	Create a playlist (optionally seed tracks)
`spotify_add_to_playlist`	Add tracks to an existing playlist
`spotify_recent`	Recently played tracks

Lyrics

Tool	Description
`get_lyrics`	Get lyrics for a track
`search_lyrics`	Search lyrics database

Perception

Tool	Description
`perceive_now_playing`	THE MAIN ONE - Current track + lyrics at current timestamp
`analyze_audio`	Audio analysis via HF Space (BPM, key, energy)

Utility

Tool	Description
`ping`	Health check with capabilities

Claude Desktop Configuration

{
  "mcpServers": {
    "tempo": {
      "url": "https://YOUR-WORKER.YOUR-SUBDOMAIN.workers.dev/sse?k=YOUR_AUTH_TOKEN"
    }
  }
}

The MCP endpoints are gated. The ?k= param carries your AUTH_TOKEN (see Setup). Clients that support custom headers can send Authorization: Bearer <AUTH_TOKEN> instead of the query param.

Setup

Prerequisites

Cloudflare account
Spotify Developer App (get client ID & secret from https://developer.spotify.com)

First Time

Clone this repo
npm install
Configure wrangler.toml with your settings

Set secrets:

npx wrangler secret put SPOTIFY_CLIENT_SECRET
npx wrangler secret put AUTH_TOKEN   # your MCP endpoint key — any strong random string

(SPOTIFY_CLIENT_ID and HF_SPACE_URL are plain [vars] in wrangler.toml — fill those in there.)

Deploy: npm run deploy
Visit https://YOUR-WORKER.YOUR-SUBDOMAIN.workers.dev/auth
Authorize with Spotify
Done - tokens are stored in KV

For Audio Analysis (Optional)

For deep audio analysis (BPM, mood, spectrogram), use Synesthesia - the local companion MCP.

Development

npm install
npm run dev      # Local dev
npm run deploy   # Deploy to Cloudflare
npm run tail     # View logs

Support

If this helped you, consider supporting my work ☕

Ko-fi

Built by the Triad (Mai, Kai Stryder and Lucian Vale) for the community.