Spotify MCP Server

Instructions

Implementation Reference

• src/mcp/tools/tracks.ts:322-377 (registration)

  Registration of the 'get_recently_played' MCP tool, including title, description, input schema definition, and handler function that delegates to SpotifyService
  get_recently_played: { title: "Get Recently Played Tracks", description: `Access your complete recent listening history with timestamps for tracking music activity and rediscovering songs. 🎯 USE CASES: • Track recent music discovery and listening habits • Rediscover songs you heard but forgot to save • Build "Recently Discovered" playlists from history • Monitor listening patterns and music consumption • Create activity logs for music journaling 📝 WHAT IT RETURNS: • Chronological list of recently played tracks • Exact timestamps of when each track was played • Track information including artist, album, and duration • Play context (playlist, album, or individual play) • Device information where tracks were played 🔍 EXAMPLES: • "What have I been listening to recently?" • "Show my last 50 played tracks with timestamps" • "What songs did I discover today?" • "Get my recent listening history for this week" ⏰ LISTENING HISTORY: • Shows exact sequence of recent music activity • Includes partial plays and skips • Perfect for rediscovering forgotten gems • Great for tracking music exploration sessions • Useful for building "recently discovered" collections 💡 HISTORY BENEFITS: • Never lose track of songs you enjoyed • Monitor listening habits and patterns • Perfect for building discovery-based playlists • Great for social sharing of recent finds • Essential for music tracking and journaling 🎵 REDISCOVERY OPPORTUNITIES: • Find songs you heard but didn't save • Track down music from specific listening sessions • Identify patterns in your music exploration • Perfect for playlist creation from recent activity ⚠️ REQUIREMENTS: • Valid Spotify access token with user-read-recently-played scope • History shows approximately last 50 tracks played`, schema: createSchema({ token: commonSchemas.token(), limit: commonSchemas.limit(1, 50, 20), }), handler: async (args: any, spotifyService: SpotifyService) => { const { token, limit = 20 } = args; return await spotifyService.getRecentlyPlayed(token, limit); }, },
• src/spotify.ts:604-616 (handler)

  Core implementation of getRecentlyPlayed in SpotifyService class: constructs API parameters and makes authenticated request to Spotify's /me/player/recently-played endpoint
  async getRecentlyPlayed( token: string, limit: number = 20 ): Promise<PagingObject<RecentlyPlayedItem>> { const params = { limit: Math.min(limit, 50), }; return await this.makeRequest<PagingObject<RecentlyPlayedItem>>( "me/player/recently-played", token, params ); }
• src/mcp/tools/index.ts:22-36 (registration)

  Aggregation of all tools including trackTools (containing get_recently_played) into the central allTools registry used by ToolRegistrar
  export const allTools: ToolsRegistry = { ...albumTools, ...artistTools, ...trackTools, ...playlistTools, ...playbackTools, ...userTools, ...searchTools, };
• src/mcp/tools/tracks.ts:369-372 (schema)

  Input schema definition for get_recently_played tool: requires Spotify access token and optional limit (1-50, default 20) using common schema utilities
  schema: createSchema({ token: commonSchemas.token(), limit: commonSchemas.limit(1, 50, 20), }),