Spotify MCP Node Server

Controle a reprodução do Spotify e gerencie playlists usando assistentes de IA e IDEs.

GitHubExperimente este MCPPatrocinado

Documentação

MCP Logo

Spotify MCP Node Server

Um servidor Node do Model Context Protocol (MCP) que permite que assistentes de IA como Claude Desktop, ou IDEs como Cursor e Windsurf controlem a reprodução do Spotify e gerenciem playlists. Ótimo para descoberta musical e curadoria criativa de playlists. Experimente pedir ao Claude algumas faixas menos conhecidas de um gênero ou similares a um artista. Você pode começar pedindo para criar uma nova playlist ou atualizar uma playlist existente.

Para um início mais rápido, a partir de maio de 2025, o Claude Desktop é a forma recomendada de usar este software. Instale o Claude Desktop para sua plataforma e siga o guia de integração abaixo.

Para cumprir os Termos de Desenvolvedor do Spotify, você deve ter uma conta Spotify Premium para usar este servidor. Além disso, se você estiver usando assistentes de IA habilitados para MCP (como o Claude) com este servidor, você deve optar por não compartilhar dados para treinamento de modelos.

Conteúdo

Exemplos de Interações

  • "Toque bootlegs menos conhecidos dos Beatles"
  • "Faça uma playlist de fusão dos Beatles e Metallica"
  • "Quais são os recursos de áudio da faixa 'Bohemian Rhapsody' do Queen?"
  • "Crie minha playlist de maratona e adicione faixas das minhas playlists de treino"

Ferramentas

Operações de Leitura

  1. searchSpotify

    • Descrição: Pesquisar faixas, álbuns, artistas ou playlists no Spotify
    • Parâmetros:
      • query (string): O termo de pesquisa
      • type (string): Tipo de item a pesquisar (track, album, artist, playlist)
      • limit (number, opcional): Número máximo de resultados a retornar (10-50)
    • Retorna: Lista de itens correspondentes com seus IDs, nomes e detalhes adicionais
    • Exemplo: searchSpotify("bohemian rhapsody", "track", 20)

  2. getNowPlaying

    • Descrição: Obter informações sobre a faixa atualmente em reprodução no Spotify
    • Parâmetros: Nenhum
    • Retorna: Objeto contendo nome da faixa, artista, álbum, progresso da reprodução, duração e estado da reprodução
    • Exemplo: getNowPlaying()

  3. getUserPlaylists

    • Descrição: Obter uma lista das playlists do usuário atual no Spotify
    • Parâmetros:
      • limit (number, opcional): Número máximo de playlists a retornar (padrão: 20)
      • offset (number, opcional): Índice da primeira playlist a retornar (padrão: 0)
    • Retorna: Matriz de playlists com seus IDs, nomes, contagens de faixas e status público
    • Exemplo: getUserPlaylists(10, 0)

  4. getPlaylistTracks

    • Descrição: Obter uma lista de faixas em uma playlist específica do Spotify
    • Parâmetros:
      • playlistId (string): O ID do Spotify da playlist
      • limit (number, opcional): Número máximo de faixas a retornar (padrão: 100)
      • offset (number, opcional): Índice da primeira faixa a retornar (padrão: 0)
    • Retorna: Matriz de faixas com seus IDs, nomes, artistas, álbum, duração e data de adição
    • Exemplo: getPlaylistTracks("37i9dQZEVXcJZyENOWUFo7")

  5. getRecentlyPlayed

    • Descrição: Recupera uma lista de faixas reproduzidas recentemente do Spotify.
    • Parâmetros:
      • limit (number, opcional): Um número especificando o número máximo de faixas a retornar.
    • Retorna: Se faixas forem encontradas, retorna uma lista formatada de faixas reproduzidas recentemente; caso contrário, uma mensagem informando: "You don't have any recently played tracks on Spotify".
    • Exemplo: getRecentlyPlayed({ limit: 10 })

  6. getRecentlyPlayed

    • Descrição: Recupera uma lista de faixas reproduzidas recentemente do Spotify.
    • Parâmetros:
      • limit (number, opcional): Um número especificando o número máximo de faixas a retornar.
    • Retorna: Se faixas forem encontradas, retorna uma lista formatada de faixas reproduzidas recentemente; caso contrário, uma mensagem informando: "You don't have any recently played tracks on Spotify".
    • Exemplo: getRecentlyPlayed({ limit: 10 })

  7. getFollowedArtists

    • Descrição: Recupera uma lista de artistas que o usuário segue no Spotify.
    • Parâmetros:
      • after (string, opcional): O último ID de artista da solicitação anterior. Cursor para paginação.
      • limit (number, opcional): Número máximo de artistas a retornar (1-50).
    • Retorna: Se artistas forem encontrados, retorna uma lista formatada de artistas seguidos; caso contrário, uma mensagem informando: "You don't follow any artists on Spotify".
    • Exemplo: getFollowedArtists({ limit: 10 })

  8. getUserTopItems

    • Descrição: Recupera uma lista dos principais artistas ou faixas do usuário.
    • Parâmetros:
      • type (string): O tipo de itens para obter os principais. Deve ser "artists" ou "tracks".
      • time_range (string): O intervalo de tempo para os principais itens. Deve ser "short_term", "medium_term" ou "long_term".
      • limit (number, opcional): Número máximo de itens a retornar (1-50).
      • offset (number, opcional): Índice do primeiro item a retornar. Padrão: 0.
    • Retorna: Se itens forem encontrados, retorna uma lista formatada dos principais itens; caso contrário, uma mensagem informando: "You don't have any top items on Spotify".
    • Exemplo: getUserTopItems({ type: "artists", time_range: "short_term", limit: 10 })
Operações de Reprodução / Criação

  1. playMusic

    • Descrição: Iniciar a reprodução de uma faixa, álbum, artista ou playlist no Spotify
    • Parâmetros:
      • uri (string, opcional): URI do Spotify do item a reproduzir (substitui tipo e ID)
      • type (string, opcional): Tipo de item a reproduzir (track, album, artist, playlist)
      • id (string, opcional): ID do Spotify do item a reproduzir
      • deviceId (string, opcional): ID do dispositivo para reproduzir
    • Retorna: Status de sucesso
    • Exemplo: playMusic({ uri: "spotify:track:6rqhFgbbKwnb9MLmUQDhG6" })
    • Alternativa: playMusic({ type: "track", id: "6rqhFgbbKwnb9MLmUQDhG6" })

  2. pausePlayback

    • Descrição: Pausar a faixa atualmente em reprodução no Spotify
    • Parâmetros:
      • deviceId (string, opcional): ID do dispositivo para pausar
    • Retorna: Status de sucesso
    • Exemplo: pausePlayback()

  3. skipToNext

    • Descrição: Avançar para a próxima faixa na fila de reprodução atual
    • Parâmetros:
      • deviceId (string, opcional): ID do dispositivo
    • Retorna: Status de sucesso
    • Exemplo: skipToNext()

  4. skipToPrevious

    • Descrição: Voltar para a faixa anterior na fila de reprodução atual
    • Parâmetros:
      • deviceId (string, opcional): ID do dispositivo
    • Retorna: Status de sucesso
    • Exemplo: skipToPrevious()

  5. createPlaylist

    • Descrição: Criar uma nova playlist no Spotify
    • Parâmetros:
      • name (string): Nome da nova playlist
      • description (string, opcional): Descrição da playlist
      • public (boolean, opcional): Se a playlist deve ser pública (padrão: false)
    • Retorna: Objeto com o ID e a URL da nova playlist
    • Exemplo: createPlaylist({ name: "Workout Mix", description: "Songs to get pumped up", public: false })

  6. addTracksToPlaylist

    • Descrição: Adicionar faixas a uma playlist existente do Spotify
    • Parâmetros:
      • playlistId (string): ID da playlist
      • trackUris (array): Matriz de URIs ou IDs de faixas para adicionar
      • position (number, opcional): Posição para inserir as faixas
    • Retorna: Status de sucesso e ID do snapshot
    • Exemplo: addTracksToPlaylist({ playlistId: "3cEYpjA9oz9GiPac4AsH4n", trackUris: ["spotify:track:4iV5W9uYEdYUVa79Axb7Rh"] })

  7. addToQueue

    • Descrição: Adiciona uma faixa, álbum, artista ou playlist à fila de reprodução atual
    • Parâmetros:
      • uri (string, opcional): URI do Spotify do item para adicionar à fila (substitui tipo e ID)
      • type (string, opcional): Tipo de item para enfileirar (track, album, artist, playlist)
      • id (string, opcional): ID do Spotify do item para enfileirar
      • deviceId (string, opcional): ID do dispositivo para enfileirar
    • Retorna: Status de sucesso
    • Exemplo: addToQueue({ uri: "spotify:track:6rqhFgbbKwnb9MLmUQDhG6" })
    • Alternativa: addToQueue({ type: "track", id: "6rqhFgbbKwnb9MLmUQDhG6" })

Configuração

Pré-requisitos

Instalação do Servidor MCP

git clone https://github.com/igorgarbuz/spotify-mcp.git
cd spotify-mcp
npm install
npm run build

Instalação do Node.js

  1. Acesse a página de download do Node.js
  2. Baixe e instale uma versão recente do Node.js para sua plataforma

Criando um Aplicativo de Desenvolvedor Spotify

  1. Acesse o Spotify Developer Dashboard
  2. Faça login com sua conta do Spotify
  3. Clique no botão "Create an App"
  4. Preencha o nome e a descrição do aplicativo
  5. Aceite os Termos de Serviço e clique em "Create"
  6. No painel do seu novo aplicativo, você verá seu Client ID
  7. Clique em "Edit Settings" e adicione uma Redirect URI (por exemplo, http://127.0.0.1:8888/callback)
  8. Salve suas alterações

Configuração da API do Spotify

Crie um arquivo spotify-config.json na raiz do projeto:

# Copy the example config file
cp spotify-config.example.json spotify-config.json

Em seguida, edite o arquivo adicionando apenas o seu client id. O accessToken, refreshToken e accessTokenExpiresAt serão gerenciados automaticamente. O redirectUri deve ser o mesmo que você adicionou no Spotify Developer Dashboard. 127.0.0.1 é a opção mais simples para o servidor MCP local.

{
  "clientId": "you-must-add-your-client-id-here",
  "redirectUri": "http://127.0.0.1:8888/callback",
  "accessToken": "your-access-token-filled-automatically",
  "refreshToken": "your-refresh-token-filled-automatically",
  "accessTokenExpiresAt": 0
}

Processo de Autenticação

A API do Spotify usa OAuth 2.0 com a extensão PKCE para autenticação segura. Você NÃO precisa de um client secret para este aplicativo.

  1. Execute o script de autenticação no diretório do repositório clonado:
npm run auth

  1. O script abrirá seu navegador na página de autorização do Spotify.

  2. Faça login no Spotify e autorize seu aplicativo.

  3. Após a autorização, o Spotify redirecionará você para a redirect URI especificada. O aplicativo lidará automaticamente com a troca do código e salvará seus tokens.

  4. O script de autenticação trocará automaticamente esse código pelos tokens de acesso e atualização.

  5. Esses tokens serão salvos no seu arquivo spotify-config.json.

{
  "clientId": "your-client-id",
  "redirectUri": "http://127.0.0.1:8888/callback",
  "accessToken": "your-access-token-filled-automatically",
  "refreshToken": "your-refresh-token-filled-automatically",
  "accessTokenExpiresAt": 0
}
  1. O servidor atualizará automaticamente o token de acesso quando necessário, então você não precisa reautenticar.

Integração com assistentes de IA

Claude Desktop

A maneira mais fácil de usar o servidor MCP do Spotify é com o Claude Desktop. Inicie a instalação do Claude Desktop e localize o arquivo de configuração do Claude, vá para Claude Settings, clique em Developer e depois em Edit Config. Adicione o seguinte à configuração com um caminho absoluto para o servidor:

{
  "mcpServers": {
    "spotify": {
      "command": "node",
      "args": ["absolute/path/to/spotify-mcp/build/index.js"]
    }
  }
}

Cursor

Para o Cursor, vá para a aba MCP em Cursor Settings (command + shift + J). Adicione um servidor com este comando:

node absolute/path/to/spotify-mcp/build/index.js

VsCode (via Cline)

Para configurar seu MCP corretamente com o Cline, certifique-se de ter a seguinte configuração de arquivo definida cline_mcp_settings.json:

{
  "mcpServers": {
    "spotify": {
      "command": "node",
      "args": ["/absolute/path/to/spotify-mcp/build/index.js"],
      "autoApprove": ["getListeningHistory", "getNowPlaying"]
    }
  }
}

Você pode adicionar ferramentas adicionais ao array de aprovação automática para executar as ferramentas sem intervenção.

Windsurf

Em Settings e depois Windsurf Settings, digite MCP na barra de pesquisa. Na seção de resultados MCP, clique em add server e depois em add custom server. Adicione a seguinte configuração:

{
  "mcpServers": {
    "spotify": {
      "command": "node",
      "args": ["absolute/path/to/spotify-mcp/build/index.js"],
    }
  }
}

Você pode adicionar ferramentas adicionais ao array de aprovação automática para executar as ferramentas sem intervenção.

Créditos

Este projeto foi inspirado pelo spotify-mcp-server de Marcel Marais. Principais modificações:

  1. O processo de autenticação foi refatorado para usar a extensão PKCE da API do Spotify, eliminando a necessidade de armazenamento local do client secret e reautenticação repetida.
  2. Foram adicionadas novas ferramentas para entender o gosto do usuário.