Spotify MCP Server

Instructions

Implementation Reference

• src/mcp/tools/playback.ts:438-441 (handler)

  The MCP tool handler for get_devices, extracting token and delegating to SpotifyService.getUserDevices

  handler: async (args: any, spotifyService: SpotifyService) => {
    const { token } = args;
    return await spotifyService.getUserDevices(token);
  },

• src/mcp/tools/playback.ts:435-437 (schema)

  Input schema definition for the get_devices tool, requiring a valid Spotify access token

  schema: createSchema({
    token: commonSchemas.token(),
  }),

• src/mcp/tools/playback.ts:393-442 (registration)

  Full registration of the get_devices tool within the playbackTools object, including title, description, schema, and handler

    get_devices: {
      title: "Get User Devices",
      description: `Retrieve all available Spotify-connected devices for the user's account.
  
  🎯 USE CASES:
  • Display device options for playback targeting
  • Build device management and control interfaces
  • Check which devices are currently online and available
  • Monitor device battery levels and connection status
  • Create smart home integrations with Spotify-enabled devices
  
  📝 WHAT IT RETURNS:
  • Complete list of user's connected devices
  • Device names, types, and unique identifiers
  • Current active state and availability status
  • Volume levels and playback capabilities
  • Device restrictions and supported features
  
  🔍 EXAMPLES:
  • "Show me all my Spotify devices"
  • "What devices can I play music on?"
  • "List my available speakers and phones"
  • "Which devices are currently online?"
  
  🔧 DEVICE TYPES:
  • Computer (desktop/laptop applications)
  • Smartphone (mobile apps)
  • Speaker (smart speakers, soundbars)
  • TV (smart TVs, streaming devices)
  • Car (automotive systems)
  • Game Console (PlayStation, Xbox)
  
  💡 DEVICE MANAGEMENT:
  • Shows real-time availability status
  • Indicates which device is currently active
  • Displays volume control capabilities
  • Shows device-specific restrictions
  • Perfect for building device selector UIs
  
  ⚠️ REQUIREMENTS:
  • Valid Spotify access token with user-read-playback-state scope
  • At least one Spotify-enabled device must be logged in`,
      schema: createSchema({
        token: commonSchemas.token(),
      }),
      handler: async (args: any, spotifyService: SpotifyService) => {
        const { token } = args;
        return await spotifyService.getUserDevices(token);
      },
    },

• src/spotify.ts:707-712 (helper)

  SpotifyService helper method implementing the core logic by calling Spotify API endpoint /me/player/devices

  async getUserDevices(token: string): Promise<{ devices: SpotifyDevice[] }> {
    return await this.makeRequest<{ devices: SpotifyDevice[] }>(
      "me/player/devices",
      token
    );
  }

• src/spotify.ts:114-122 (schema)

  TypeScript interface defining the structure of SpotifyDevice objects returned by the tool

  export interface SpotifyDevice {
    id: string;
    is_active: boolean;
    is_private_session: boolean;
    is_restricted: boolean;
    name: string;
    type: string;
    volume_percent: number | null;
  }