get_audio_features

Retrieve audio analysis data for Spotify tracks including tempo, key, energy, danceability, and other musical characteristics. Analyze up to 100 tracks in a single API call to understand their sonic properties.

Instructions

Get audio features for one or more tracks (tempo, key, energy, danceability, etc).

Args:
    track_ids: Single track ID or list of track IDs (up to 100)

Returns:
    Dict with 'features' list containing audio features for each track.
    Features include: tempo, key, mode, time_signature, danceability, energy,
    valence, loudness, speechiness, acousticness, instrumentalness, liveness.

Note: Batch lookup is efficient - 100 tracks = 1 API call.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`track_ids`	Yes

Implementation Reference

src/spotify_mcp/fastmcp_server.py:790-838 (handler)

The handler function for the 'get_audio_features' tool. Registered via @mcp.tool() decorator. Normalizes input track IDs, calls Spotify API's audio_features endpoint, parses results using AudioFeatures Pydantic model, and returns structured features data.

@mcp.tool()
@log_tool_execution
def get_audio_features(track_ids: str | list[str]) -> dict[str, Any]:
    """Get audio features for one or more tracks (tempo, key, energy, danceability, etc).

    Args:
        track_ids: Single track ID or list of track IDs (up to 100)

    Returns:
        Dict with 'features' list containing audio features for each track.
        Features include: tempo, key, mode, time_signature, danceability, energy,
        valence, loudness, speechiness, acousticness, instrumentalness, liveness.

    Note: Batch lookup is efficient - 100 tracks = 1 API call.
    """
    try:
        # Normalize to list
        ids = [track_ids] if isinstance(track_ids, str) else track_ids

        if len(ids) > 100:
            raise ValueError("Maximum 100 track IDs per request (Spotify API limit)")

        logger.info(f"🎼 Getting audio features for {len(ids)} track(s)")
        result = spotify_client.audio_features(ids)

        features_list = []
        for features in result:
            if features:
                audio = AudioFeatures(
                    id=features["id"],
                    tempo=features.get("tempo"),
                    key=features.get("key"),
                    mode=features.get("mode"),
                    time_signature=features.get("time_signature"),
                    danceability=features.get("danceability"),
                    energy=features.get("energy"),
                    valence=features.get("valence"),
                    loudness=features.get("loudness"),
                    speechiness=features.get("speechiness"),
                    acousticness=features.get("acousticness"),
                    instrumentalness=features.get("instrumentalness"),
                    liveness=features.get("liveness"),
                )
                features_list.append(audio.model_dump())

        return {"features": features_list}
    except SpotifyException as e:
        raise convert_spotify_error(e) from e

src/spotify_mcp/fastmcp_server.py:106-122 (schema)

Pydantic BaseModel defining the schema for audio features data returned by the tool. Used to structure and validate the output from Spotify's audio_features API.

class AudioFeatures(BaseModel):
    """Audio features for a track."""

    id: str
    tempo: float | None = None
    key: int | None = None
    mode: int | None = None
    time_signature: int | None = None
    danceability: float | None = None
    energy: float | None = None
    valence: float | None = None
    loudness: float | None = None
    speechiness: float | None = None
    acousticness: float | None = None
    instrumentalness: float | None = None
    liveness: float | None = None

src/spotify_mcp/fastmcp_server.py:790-790 (registration)
The @mcp.tool() decorator registers the get_audio_features function as an MCP tool, using the function name as the tool name.
```
@mcp.tool()
```

Spotify MCP Server