playback_control
Control Spotify playback by starting, pausing, skipping tracks, or checking current status. Use this tool to manage music playback through the Spotify MCP Server.
Instructions
Control Spotify playback.
Args:
action: Action ('get', 'start', 'pause', 'skip')
track_id: Track ID to play (for 'start')
num_skips: Number of tracks to skip
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | ||
| track_id | No | ||
| num_skips | No |
Implementation Reference
- The playback_control tool handler: controls Spotify playback with actions 'get', 'start', 'pause', 'skip'. Includes registration via @mcp.tool() decorator.@mcp.tool() @log_tool_execution def playback_control( action: str, track_id: str | None = None, num_skips: int = 1 ) -> PlaybackState: """Control Spotify playback. Args: action: Action ('get', 'start', 'pause', 'skip') track_id: Track ID to play (for 'start') num_skips: Number of tracks to skip """ try: if action == "get": logger.info("🎵 Getting current playback state") result = spotify_client.current_user_playing_track() elif action == "start": if track_id: logger.info(f"🎵 Starting playback of track: {track_id}") spotify_client.start_playback(uris=[f"spotify:track:{track_id}"]) else: logger.info("🎵 Resuming playback") spotify_client.start_playback() result = spotify_client.current_user_playing_track() elif action == "pause": logger.info("🎵 Pausing playback") spotify_client.pause_playback() result = spotify_client.current_user_playing_track() elif action == "skip": logger.info(f"🎵 Skipping {num_skips} track(s)") for _ in range(num_skips): spotify_client.next_track() result = spotify_client.current_user_playing_track() else: raise ValueError(f"Invalid action: {action}") # Parse result track = None if result and result.get("item"): track = parse_track(result["item"]) return PlaybackState( is_playing=result.get("is_playing", False) if result else False, track=track, device=result.get("device", {}).get("name") if result and result.get("device") else None, volume=result.get("device", {}).get("volume_percent") if result and result.get("device") else None, shuffle=result.get("shuffle_state", False) if result else False, repeat=result.get("repeat_state", "off") if result else "off", progress_ms=result.get("progress_ms") if result else None, ) except SpotifyException as e: raise convert_spotify_error(e) from e
- Pydantic schema model PlaybackState used as return type for the tool.class PlaybackState(BaseModel): """Current playback state.""" is_playing: bool track: Track | None = None device: str | None = None volume: int | None = None shuffle: bool = False repeat: str = "off" progress_ms: int | None = None
- Pydantic schema model Track used within PlaybackState.class Track(BaseModel): """A Spotify track with metadata.""" name: str id: str artist: str artists: list[str] | None = None album: str | None = None album_id: str | None = None release_date: str | None = None duration_ms: int | None = None popularity: int | None = None external_urls: dict[str, str] | None = None
- Helper function parse_track to convert Spotify API track data to Track model, used in playback_control.def parse_track(item: dict[str, Any]) -> Track: """Parse Spotify track data into Track model.""" album_data = item.get("album", {}) return Track( name=item["name"], id=item["id"], artist=item["artists"][0]["name"] if item.get("artists") else "Unknown", artists=[a["name"] for a in item.get("artists", [])], album=album_data.get("name"), album_id=album_data.get("id"), release_date=album_data.get("release_date"), duration_ms=item.get("duration_ms"), popularity=item.get("popularity"), external_urls=item.get("external_urls"), )