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

src/spotify_mcp/fastmcp_server.py:212-269 (handler)

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

src/spotify_mcp/fastmcp_server.py:55-64 (schema)

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

src/spotify_mcp/fastmcp_server.py:40-52 (schema)

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

src/spotify_mcp/fastmcp_server.py:124-138 (helper)

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"),
    )

Spotify MCP Server