MCP Claude Spotify

Instructions

Input Schema

Input Schema (JSON Schema)

Implementation Reference

• index.ts:1080-1144 (handler)

  Handler implementation for the get-current-playback tool. Fetches current playback state from Spotify API endpoint /me/player, formats the response with track info, progress, device details, shuffle and repeat status.
  if (name === "get-current-playback") { const playback = await spotifyApiRequest("/me/player"); if (!playback) { return { content: [ { type: "text", text: "No active playback found. Make sure you have an active Spotify session.", }, ], }; } let responseText = ""; if (playback.item) { responseText = ` Currently ${playback.is_playing ? "Playing" : "Paused"}: Track: ${playback.item.name} Artist: ${playback.item.artists.map((a: any) => a.name).join(", ")} Album: ${playback.item.album.name} Progress: ${Math.floor(playback.progress_ms / 1000 / 60)}:${( Math.floor(playback.progress_ms / 1000) % 60 ) .toString() .padStart(2, "0")} / ${Math.floor( playback.item.duration_ms / 1000 / 60 )}:${(Math.floor(playback.item.duration_ms / 1000) % 60) .toString() .padStart(2, "0")} Device: ${playback.device.name} Volume: ${playback.device.volume_percent}% Shuffle: ${playback.shuffle_state ? "On" : "Off"} Repeat: ${ playback.repeat_state === "off" ? "Off" : playback.repeat_state === "context" ? "Context" : "Track" }`; } else { responseText = ` No track currently playing. Device: ${playback.device.name} Volume: ${playback.device.volume_percent}% Shuffle: ${playback.shuffle_state ? "On" : "Off"} Repeat: ${ playback.repeat_state === "off" ? "Off" : playback.repeat_state === "context" ? "Context" : "Track" }`; } return { content: [ { type: "text", text: responseText, }, ], }; }
• index.ts:663-669 (registration)

  Tool registration in the ListTools response, including name, description, and empty input schema.
  name: "get-current-playback", description: "Get information about the user's current playback state", inputSchema: { type: "object", properties: {}, }, },
• index.ts:665-668 (schema)

  Input schema definition for the tool (empty object, no parameters required).
  inputSchema: { type: "object", properties: {}, },
• index.ts:299-423 (helper)

  Helper function spotifyApiRequest used by the handler to make authenticated requests to Spotify API, including token refresh logic.
  async function spotifyApiRequest(endpoint: string, method: string = "GET", data: any = null) { console.error(`Starting API request to ${endpoint}`); if (!accessToken || !refreshToken) { console.error(`No tokens in memory, trying to load from file...`); try { if (fs.existsSync(TOKEN_PATH)) { const fileContent = fs.readFileSync(TOKEN_PATH, 'utf8'); console.error(`Read ${fileContent.length} bytes from token file`); if (fileContent.trim() !== '') { const tokenData = JSON.parse(fileContent); accessToken = tokenData.accessToken; refreshToken = tokenData.refreshToken; tokenExpirationTime = tokenData.tokenExpirationTime; console.error(`Tokens loaded successfully`); } else { console.error(`Token file is empty, cannot load tokens`); } } else { console.error(`Token file does not exist: ${TOKEN_PATH}`); } } catch (err) { console.error(`Error loading tokens from file: ${err}`); } } if (!accessToken) { console.error(`No access token available for request to ${endpoint}`); throw new Error("Not authenticated. Please authorize the app first."); } const now = Date.now(); if (now >= tokenExpirationTime - 60000) { if (refreshToken) { try { console.error(`Token expired, attempting to refresh...`); const response = await axios.post( `${SPOTIFY_AUTH_BASE}/api/token`, querystring.stringify({ grant_type: "refresh_token", refresh_token: refreshToken, }), { headers: { "Content-Type": "application/x-www-form-urlencoded", Authorization: `Basic ${Buffer.from( `${CLIENT_ID}:${CLIENT_SECRET}` ).toString("base64")}`, }, } ); accessToken = response.data.access_token; tokenExpirationTime = now + response.data.expires_in * 1000; if (response.data.refresh_token) { refreshToken = response.data.refresh_token; } console.error(`Token refreshed successfully, expires at ${new Date(tokenExpirationTime).toISOString()}`); try { if (!fs.existsSync(TOKEN_DIR)) { fs.mkdirSync(TOKEN_DIR, { recursive: true }); } const tokenData = JSON.stringify({ accessToken, refreshToken, tokenExpirationTime }, null, 2); fs.writeFileSync(TOKEN_PATH, tokenData); console.error(`Refreshed tokens saved to file`); } catch (saveError) { console.error(`Failed to save refreshed tokens: ${saveError}`); } } catch (refreshError) { console.error(`Failed to refresh token: ${refreshError}`); accessToken = null; refreshToken = null; tokenExpirationTime = 0; throw new Error("Authentication expired. Please authenticate again."); } } else { console.error(`Token expired but no refresh token available`); accessToken = null; tokenExpirationTime = 0; throw new Error("Authentication expired. Please authenticate again."); } } console.error(`Making authenticated request to ${endpoint}`); try { const response = await axios({ method, url: `${SPOTIFY_API_BASE}${endpoint}`, headers: { Authorization: `Bearer ${accessToken}`, "Content-Type": "application/json", }, data: data ? data : undefined, }); console.error(`Request to ${endpoint} succeeded`); return response.data; } catch (error: any) { console.error(`Spotify API error: ${error.message}`); if (error.response) { console.error(`Status: ${error.response.status}`); console.error(`Data:`, error.response.data); if (error.response.status === 401) { console.error(`Token appears to be invalid, clearing tokens`); accessToken = null; refreshToken = null; tokenExpirationTime = 0; throw new Error("Authorization expired. Please authenticate again."); } } throw new Error(`Spotify API error: ${error.message}`); } }