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

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

First Time

1. Clone this repo
2. npm install
3. Configure wrangler.toml with your settings
4. 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.)
5. Deploy: npm run deploy
6. Visit https://YOUR-WORKER.YOUR-SUBDOMAIN.workers.dev/auth
7. Authorize with Spotify
8. 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.