---
name: spotify
description: Full Spotify music intelligence, catalog search, playback control, playlist curation, party queueing, and personal listening history. Use when the user asks to search for music/podcasts/audiobooks, control Spotify playback, queue tracks, check what is currently playing, create or curate playlists (including collaborative mixes for friends), or inspect listening history and top tracks.
---

# 🎵 Spotify Skill for OpenClaw

Full integration with the **Spotify Web API** powered by `mcp-server-spotify`.

## 🛠️ MCP Tools & Capabilities

You have access to 35+ dedicated Spotify MCP tools:

### 1. Catalog Search
- `search(query, types, limit)`: Search for tracks, artists, albums, playlists, shows, episodes, or audiobooks.
  - `types`: array containing `"track"`, `"artist"`, `"album"`, `"playlist"`, `"show"`, `"episode"`, `"audiobook"`.
  - Returns Spotify URIs (`spotify:track:...`), titles, artist names, album info, and web URLs (`https://open.spotify.com/...`).

### 2. Playback & Device Control
- `get_playback_state()`: Returns current player status, active device, shuffle/repeat states, and track progress.
- `get_currently_playing()`: Quick status of the currently playing track or episode.
- `play(device_id, context_uri, uris, position_ms)`: Start or resume playback. Can play a specific playlist/album URI (`context_uri`) or a list of track URIs (`uris`).
- `pause(device_id)`: Pause active playback.
- `next_track(device_id)` / `previous_track(device_id)`: Skip tracks.
- `seek(position_ms, device_id)`: Seek to a position in milliseconds.
- `set_volume(volume_percent, device_id)`: Set volume (0-100).
- `toggle_shuffle(state, device_id)`: Enable or disable shuffle.
- `transfer_playback(device_ids, play)`: Transfer active playback to another Spotify Connect device.
- `get_devices()`: List available Spotify Connect devices (TVs, laptops, speakers, mobile).
- `add_to_queue(uri, device_id)`: Add a track/episode URI to the user's active playback queue.
- `get_queue()`: Inspect currently playing item and upcoming queued items.

### 3. Playlists & Collaboration
- `create_playlist(name, description, public)`: Create a new Spotify playlist for the user.
- `get_playlist(playlist_id)`: Retrieve playlist metadata and owner.
- `get_playlist_items(playlist_id, limit, offset)`: List tracks inside a playlist.
- `add_playlist_items(playlist_id, uris, position)`: Add track URIs to an existing playlist (supports batch addition).
- `remove_playlist_items(playlist_id, uris)`: Remove tracks from a playlist.
- `reorder_playlist_items(playlist_id, range_start, insert_before)`: Reorder songs in a playlist.
- `get_my_playlists(limit, offset)`: List current user's saved and created playlists.

### 4. Personal History, Taste & Social
- `get_recently_played(limit)`: History of recently played tracks with timestamps.
- `get_my_top_items(type, time_range, limit)`: Fetch top tracks or top artists over short (`"short_term"` = 4 weeks), medium (`"medium_term"` = 6 months), or long term (`"long_term"` = years).
- `get_my_profile()`: User's profile details and country.
- `whoami()`: Diagnostic helper returning authentication state, active device, and granted scopes.

---

## 📱 Telegram Presentation Guidelines

When formatting Spotify results or music recommendations for Telegram:
- **Clean Markdown Links**: Always format track and playlist links nicely:
  - `▶️ [Track Title - Artist Name](https://open.spotify.com/track/...)`
  - `📁 [Playlist Name](https://open.spotify.com/playlist/...)`
- **Current Playing Card**: When asked *"what's playing?"*:
  - Display: `🎶 *Track Title* by *Artist*\n💿 *Album Title* (Year)\n⏱️ mm:ss / mm:ss [■■■□□□□□□□]\n🔗 [Open in Spotify](url)`
- **Friend Requests / Party Aux DJ**:
  - When a friend in a Telegram group asks to add a song:
    1. Search Spotify for the best match via `search`.
    2. Add to active queue (`add_to_queue`) or the group's party playlist (`add_playlist_items`).
    3. Confirm with a friendly message: *"Added 🎵 [Song - Artist](url) to the queue! Next up."*

---

## 🏡 Home Assistant (Sonos & Hue) Synergy

OpenClaw has access to both **Spotify MCP** and **Home Assistant MCP (`ha-mcp`)**:
- **Spotify MCP is the Music Brain**: Use it to search the global catalog, find Spotify URIs, build playlists, and inspect listening history.
- **Home Assistant is the Physical Hardware Controller**:
  - Home Assistant's `media_player.play_media` requires a Spotify URI (`spotify:track:...`, `spotify:playlist:...`).
  - When asked to *"Play X in the living room / on Sonos"*:
    1. Use `search` from Spotify MCP to get the exact `spotify:track:...` or `spotify:playlist:...` URI.
    2. Call `ha-mcp:ha_call_service`:
       - Domain: `media_player`
       - Service: `play_media`
       - Service Data: `{"media_content_id": "<spotify_uri>", "media_content_type": "music"}`
       - Target: `{"entity_id": "media_player.sonos_..."}`
    3. If asked for ambience or party lighting, call `ha-mcp:ha_call_service` on `light.turn_on` or activate Hue scenes simultaneously.