Spotify MCP Server

Implementation Reference

• mcp/spotify-mcp-sse.ts:197-255 (handler)

  The handler function for the 'search-tracks' tool. It retrieves a valid Spotify access token, performs a search query to the Spotify API for tracks, processes the response to extract relevant track information (id, name, artist, album, uri), and returns the results as a formatted JSON string in the MCP response format. Handles errors appropriately.

  async ({ query, limit }) => {
    try {
      const accessToken = await getValidAccessToken();
  
      const response = await fetch(
        `https://api.spotify.com/v1/search?q=${encodeURIComponent(
          query
        )}&type=track&limit=${limit}`,
        {
          headers: {
            Authorization: `Bearer ${accessToken}`,
          },
        }
      );
  
      const data = (await response.json()) as any;
  
      if (!response.ok) {
        return {
          content: [
            {
              type: "text",
              text: `Error searching tracks: ${JSON.stringify(data)}`,
            },
          ],
          isError: true,
        };
      }
  
      const tracks = data.tracks.items.map((track: any) => ({
        id: track.id,
        name: track.name,
        artist: track.artists.map((artist: any) => artist.name).join(", "),
        album: track.album.name,
        uri: track.uri,
      }));
  
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(tracks, null, 2),
          },
        ],
      };
    } catch (error) {
      return {
        content: [
          {
            type: "text",
            text: `Failed to search tracks: ${
              error instanceof Error ? error.message : String(error)
            }`,
          },
        ],
        isError: true,
      };
    }
  }

• mcp/spotify-mcp-sse.ts:188-196 (schema)

  Zod schema defining the input parameters for the search-tracks tool: a required 'query' string and an optional 'limit' number (1-50, default 10).

  {
    query: z.string().describe("Search query for tracks"),
    limit: z
      .number()
      .min(1)
      .max(50)
      .default(10)
      .describe("Number of results to return"),
  },

• mcp/spotify-mcp-sse.ts:186-256 (registration)

  Registration of the 'search-tracks' tool on the MCP server using server.tool(), including name, input schema, and handler function.

  server.tool(
    "search-tracks",
    {
      query: z.string().describe("Search query for tracks"),
      limit: z
        .number()
        .min(1)
        .max(50)
        .default(10)
        .describe("Number of results to return"),
    },
    async ({ query, limit }) => {
      try {
        const accessToken = await getValidAccessToken();
  
        const response = await fetch(
          `https://api.spotify.com/v1/search?q=${encodeURIComponent(
            query
          )}&type=track&limit=${limit}`,
          {
            headers: {
              Authorization: `Bearer ${accessToken}`,
            },
          }
        );
  
        const data = (await response.json()) as any;
  
        if (!response.ok) {
          return {
            content: [
              {
                type: "text",
                text: `Error searching tracks: ${JSON.stringify(data)}`,
              },
            ],
            isError: true,
          };
        }
  
        const tracks = data.tracks.items.map((track: any) => ({
          id: track.id,
          name: track.name,
          artist: track.artists.map((artist: any) => artist.name).join(", "),
          album: track.album.name,
          uri: track.uri,
        }));
  
        return {
          content: [
            {
              type: "text",
              text: JSON.stringify(tracks, null, 2),
            },
          ],
        };
      } catch (error) {
        return {
          content: [
            {
              type: "text",
              text: `Failed to search tracks: ${
                error instanceof Error ? error.message : String(error)
              }`,
            },
          ],
          isError: true,
        };
      }
    }
  );

• mcp/spotify-mcp-sse.ts:35-92 (helper)

  Helper function to obtain a valid Spotify access token, checking current token validity and refreshing it if expired using the refresh token.

  async function getValidAccessToken() {
    if (!spotifyAuthInfo.accessToken || !spotifyAuthInfo.refreshToken) {
      throw new Error(
        "No access token available. Please set credentials first using the set-spotify-credentials tool."
      );
    }
  
    try {
      // Try using current token
      const response = await fetch("https://api.spotify.com/v1/me", {
        headers: {
          Authorization: `Bearer ${spotifyAuthInfo.accessToken}`,
        },
      });
  
      // If token works, return it
      if (response.ok) {
        return spotifyAuthInfo.accessToken;
      }
  
      console.error("Access token expired, refreshing...");
  
      // If token doesn't work, refresh it
      const refreshResponse = await fetch(
        "https://accounts.spotify.com/api/token",
        {
          method: "POST",
          headers: {
            "Content-Type": "application/x-www-form-urlencoded",
            Authorization:
              "Basic " +
              Buffer.from(
                spotifyAuthInfo.clientId + ":" + spotifyAuthInfo.clientSecret
              ).toString("base64"),
          },
          body: new URLSearchParams({
            grant_type: "refresh_token",
            refresh_token: spotifyAuthInfo.refreshToken,
          }),
        }
      );
  
      const data = (await refreshResponse.json()) as any;
  
      if (data.access_token) {
        console.error("Successfully refreshed access token");
        spotifyAuthInfo.accessToken = data.access_token;
        return spotifyAuthInfo.accessToken;
      }
  
      throw new Error("Failed to refresh access token");
    } catch (error) {
      throw new Error(
        "Error with access token: " +
          (error instanceof Error ? error.message : String(error))
      );
    }
  }

• mcp/spotify-mcp.ts:184-242 (handler)

  Identical handler implementation for 'search-tracks' in the stdio transport version of the server.

  async ({ query, limit }) => {
    try {
      const accessToken = await getValidAccessToken();
  
      const response = await fetch(
        `https://api.spotify.com/v1/search?q=${encodeURIComponent(
          query
        )}&type=track&limit=${limit}`,
        {
          headers: {
            Authorization: `Bearer ${accessToken}`,
          },
        }
      );
  
      const data = (await response.json()) as any;
  
      if (!response.ok) {
        return {
          content: [
            {
              type: "text",
              text: `Error searching tracks: ${JSON.stringify(data)}`,
            },
          ],
          isError: true,
        };
      }
  
      const tracks = data.tracks.items.map((track: any) => ({
        id: track.id,
        name: track.name,
        artist: track.artists.map((artist: any) => artist.name).join(", "),
        album: track.album.name,
        uri: track.uri,
      }));
  
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(tracks, null, 2),
          },
        ],
      };
    } catch (error) {
      return {
        content: [
          {
            type: "text",
            text: `Failed to search tracks: ${
              error instanceof Error ? error.message : String(error)
            }`,
          },
        ],
        isError: true,
      };
    }
  }