# Spotify

import ToolInfo from "@/app/_components/tool-info";
import Badges from "@/app/_components/badges";
import TabbedCodeBlock from "@/app/_components/tabbed-code-block";
import TableOfContents from "@/app/_components/table-of-contents";
import ToolFooter from "@/app/_components/tool-footer";
import { Callout } from "nextra/components";

<ToolInfo
  description="Enable agents to interact with Spotify tracks."
  author="Arcade"
  authType="oauth2"
  authProviderName="Spotify"
  versions={["0.1.0"]}
/>

<Callout type="warning">
  This Toolkit is not available in Arcade Cloud. You can use these tools with a
  [self-hosted](/guides/deployment-hosting/configure-engine) instance of Arcade.
</Callout>

<br />

<Badges repo="arcadeai/arcade_spotify" />

The Arcade Spotify MCP Server provides a pre-built set of tools for interacting with Spotify. These tools make it easy to build agents and AI apps that can:

- Get information about tracks
- Search for tracks
- Control playback

## Available Tools

These tools are currently available in the Arcade Spotify MCP Sever.

<TableOfContents
  headers={["Tool Name", "Description"]}
  data={[
    ["Spotify.GetTrackFromId", "Get information about a track"],
    [
      "Spotify.AdjustPlaybackPosition",
      "Adjust the playback position within the currently playing track. Note: This tool currently requires a self-hosted instance of Arcade.",
    ],
    [
      "Spotify.SkipToPreviousTrack",
      "Skip to the previous track in the user's queue, if any. Note: This tool currently requires a self-hosted instance of Arcade.",
    ],
    [
      "Spotify.SkipToNextTrack",
      "Skip to the next track in the user's queue, if any. Note: This tool currently requires a self-hosted instance of Arcade.",
    ],
    [
      "Spotify.PausePlayback",
      "Pause the currently playing track, if any. Note: This tool currently requires a self-hosted instance of Arcade.",
    ],
    [
      "Spotify.ResumePlayback",
      "Resume the currently playing track, if any. Note: This tool currently requires a self-hosted instance of Arcade.",
    ],
    [
      "Spotify.StartTracksPlaybackById",
      "Start playback of a list of tracks (songs). Note: This tool currently requires a self-hosted instance of Arcade.",
    ],
    [
      "Spotify.GetPlaybackState",
      "Get information about the user's current playback state, including track or episode, and active device. Note: This tool currently requires a self-hosted instance of Arcade.",
    ],
    [
      "Spotify.GetCurrentlyPlaying",
      "Get information about the user's currently playing track. Note: This tool currently requires a self-hosted instance of Arcade.",
    ],
    [
      "Spotify.PlayArtistByName",
      "Plays a song by an artist and queues four more songs by the same artist. Note: This tool currently requires a self-hosted instance of Arcade.",
    ],
    [
      "Spotify.PlayTrackByName",
      "Plays a song by name. Note: This tool currently requires a self-hosted instance of Arcade.",
    ],
    [
      "Spotify.GetAvailableDevices",
      "Get the available devices. Note: This tool currently requires a self-hosted instance of Arcade.",
    ],
    [
      "Spotify.Search",
      "Search Spotify catalog information. Note: This tool currently requires a self-hosted instance of Arcade.",
    ],
  ]}
/>

<Callout>
  If you need to perform an action that's not listed here, you can [get in touch
  with us](mailto:contact@arcade.dev) to request a new tool, or [create your own
  tools](/guides/create-tools/tool-basics/build-mcp-server) with the [Spotify auth
  provider](/references/auth-providers/spotify#using-spotify-auth-in-custom-tools).
</Callout>

## Spotify.GetTrackFromId

<br />
<TabbedCodeBlock
  tabs={[
    {
      label: "Call the Tool with User Authorization",
      content: {
        Python: [
          "/examples/integrations/resources/integrations/spotify/get_track_from_id_example_call_tool.py",
        ],
        JavaScript: [
          "/examples/integrations/resources/integrations/spotify/get_track_from_id_example_call_tool.js",
        ],
      },
    },
  ]}
/>

Get information about a track

**Parameters**

- `track_id` _(string, required)_ The Spotify ID of the track

---

## Spotify.AdjustPlaybackPosition

<br />
<TabbedCodeBlock
  tabs={[
    {
      label: "Call the Tool with User Authorization",
      content: {
        Python: [
          "/examples/integrations/resources/integrations/spotify/adjust_playback_position_example_call_tool.py",
        ],
        JavaScript: [
          "/examples/integrations/resources/integrations/spotify/adjust_playback_position_example_call_tool.js",
        ],
      },
    },
  ]}
/>

Adjust the playback position within the currently playing track.

Knowledge of the current playback state is NOT needed to use this tool as it handles clamping the position to valid start/end boundaries to prevent overshooting or negative values.

This tool allows you to seek to a specific position within the currently playing track. You can either provide an absolute position in milliseconds or a relative position from the current playback position in milliseconds.

Note: Either absolute_position_ms or relative_position_ms must be provided, but not both.

**Parameters**

- `absolute_position_ms` _(integer, optional)_ The absolute position in milliseconds to seek to

- `relative_position_ms` _(integer, optional)_ The relative position from the current playback position in milliseconds to seek to

---

## Spotify.SkipToPreviousTrack

<br />
<TabbedCodeBlock
  tabs={[
    {
      label: "Call the Tool with User Authorization",
      content: {
        Python: [
          "/examples/integrations/resources/integrations/spotify/skip_to_previous_track_example_call_tool.py",
        ],
        JavaScript: [
          "/examples/integrations/resources/integrations/spotify/skip_to_previous_track_example_call_tool.js",
        ],
      },
    },
  ]}
/>

Skip to the previous track in the user's queue, if any

---

## Spotify.SkipToNextTrack

<br />
<TabbedCodeBlock
  tabs={[
    {
      label: "Call the Tool with User Authorization",
      content: {
        Python: [
          "/examples/integrations/resources/integrations/spotify/skip_to_next_track_example_call_tool.py",
        ],
        JavaScript: [
          "/examples/integrations/resources/integrations/spotify/skip_to_next_track_example_call_tool.js",
        ],
      },
    },
  ]}
/>

Skip to the next track in the user's queue, if any

---

## Spotify.PausePlayback

<br />
<TabbedCodeBlock
  tabs={[
    {
      label: "Call the Tool with User Authorization",
      content: {
        Python: [
          "/examples/integrations/resources/integrations/spotify/pause_playback_example_call_tool.py",
        ],
        JavaScript: [
          "/examples/integrations/resources/integrations/spotify/pause_playback_example_call_tool.js",
        ],
      },
    },
  ]}
/>

Pause the currently playing track, if any

---

## Spotify.ResumePlayback

<br />
<TabbedCodeBlock
  tabs={[
    {
      label: "Call the Tool with User Authorization",
      content: {
        Python: [
          "/examples/integrations/resources/integrations/spotify/resume_playback_example_call_tool.py",
        ],
        JavaScript: [
          "/examples/integrations/resources/integrations/spotify/resume_playback_example_call_tool.js",
        ],
      },
    },
  ]}
/>

Resume the currently playing track, if any

---

## Spotify.StartTracksPlaybackById

<br />
<TabbedCodeBlock
  tabs={[
    {
      label: "Call the Tool with User Authorization",
      content: {
        Python: [
          "/examples/integrations/resources/integrations/spotify/start_tracks_playback_by_id_example_call_tool.py",
        ],
        JavaScript: [
          "/examples/integrations/resources/integrations/spotify/start_tracks_playback_by_id_example_call_tool.js",
        ],
      },
    },
  ]}
/>

Start playback of a list of tracks (songs)

**Parameters**

- `track_ids` _(array, required)_ A list of Spotify track (song) IDs to play. Order of execution is not guarenteed.

- `position_ms` _(integer, optional)_ The position in milliseconds to start the first track from

---

## Spotify.GetPlaybackState

<br />
<TabbedCodeBlock
  tabs={[
    {
      label: "Call the Tool with User Authorization",
      content: {
        Python: [
          "/examples/integrations/resources/integrations/spotify/get_playback_state_example_call_tool.py",
        ],
        JavaScript: [
          "/examples/integrations/resources/integrations/spotify/get_playback_state_example_call_tool.js",
        ],
      },
    },
  ]}
/>

Get information about the user's current playback state, including track or episode, and active device. This tool does not perform any actions. Use other tools to control playback.

---

## Spotify.GetCurrentlyPlaying

<br />
<TabbedCodeBlock
  tabs={[
    {
      label: "Call the Tool with User Authorization",
      content: {
        Python: [
          "/examples/integrations/resources/integrations/spotify/get_currently_playing_example_call_tool.py",
        ],
        JavaScript: [
          "/examples/integrations/resources/integrations/spotify/get_currently_playing_example_call_tool.js",
        ],
      },
    },
  ]}
/>

Get information about the user's currently playing track

---

## Spotify.PlayArtistByName

<br />
<TabbedCodeBlock
  tabs={[
    {
      label: "Call the Tool with User Authorization",
      content: {
        Python: [
          "/examples/integrations/resources/integrations/spotify/play_artist_by_name_example_call_tool.py",
        ],
        JavaScript: [
          "/examples/integrations/resources/integrations/spotify/play_artist_by_name_example_call_tool.js",
        ],
      },
    },
  ]}
/>

Plays a song by an artist and queues four more songs by the same artist

**Parameters**

- `name` _(string, required)_ The name of the artist to play

---

## Spotify.PlayTrackByName

<br />
<TabbedCodeBlock
  tabs={[
    {
      label: "Call the Tool with User Authorization",
      content: {
        Python: [
          "/examples/integrations/resources/integrations/spotify/play_track_by_name_example_call_tool.py",
        ],
        JavaScript: [
          "/examples/integrations/resources/integrations/spotify/play_track_by_name_example_call_tool.js",
        ],
      },
    },
  ]}
/>

Plays a song by name

**Parameters**

- `track_name` _(string, required)_ The name of the track to play

- `artist_name` _(string, optional)_ The name of the artist of the track

## Spotify.GetAvailableDevices

<br />
<TabbedCodeBlock
  tabs={[
    {
      label: "Call the Tool with User Authorization",
      content: {
        Python: [
          "/examples/integrations/resources/integrations/spotify/get_available_devices_example_call_tool.py",
        ],
        JavaScript: [
          "/examples/integrations/resources/integrations/spotify/get_available_devices_example_call_tool.js",
        ],
      },
    },
  ]}
/>

Get the available devices

---

## Spotify.Search

<br />
<TabbedCodeBlock
  tabs={[
    {
      label: "Call the Tool with User Authorization",
      content: {
        Python: [
          "/examples/integrations/resources/integrations/spotify/search_example_call_tool.py",
        ],
        JavaScript: [
          "/examples/integrations/resources/integrations/spotify/search_example_call_tool.js",
        ],
      },
    },
  ]}
/>

Search Spotify catalog information

Explanation of the q parameter: You can narrow down your search using field filters. The available filters are album, artist, track, year, upc, tag:hipster, tag:new, isrc, and genre. Each field filter only applies to certain result types.

    The artist and year filters can be used while searching albums, artists and tracks. You can filter on a single year or a range (e.g. 1955-1960).
    The album filter can be used while searching albums and tracks.
    The genre filter can be used while searching artists and tracks.
    The isrc and track filters can be used while searching tracks.
    The upc, tag:new and tag:hipster filters can only be used while searching albums. The tag:new filter will return albums released in the past two weeks and tag:hipster can be used to return only albums with the lowest 10% popularity.

    Example: q="remaster track:Doxy artist:Miles Davis"

**Parameters**

- `q` _(string, required)_ The search query

- `types` _(array, required)_ The types of results to return, Valid values are 'album', 'artist', 'playlist', 'track', 'show', 'episode', 'audiobook'

- `limit` _(integer, optional)_ The maximum number of results to return. Defaults to `1`.

<ToolFooter pipPackageName="arcade_spotify" />