MCP Spotify AI Assistant

Um assistente de IA que controla funcionalidades do Spotify como reprodução, playlists e pesquisa usando o Model Context Protocol (MCP).

GitHub

Experimente este MCPPatrocinado

Documentação

MCP Spotify AI Assistant

Um servidor Model Context Protocol (MCP) que permite ao Claude controlar recursos do Spotify.

Conteúdo

Exemplos de Interações
Ferramentas
- Operações de Leitura
- Operações de Escrita
Configuração
Integração com o Claude Desktop

Exemplos de Interações

"Você pode adicionar as 5 melhores músicas do Coldplay à minha playlist vibes?"
"Quais são as músicas que mais ouvi no último mês?"
"Você pode embaralhar minhas músicas favoritas?"

Ferramentas

Operações de Leitura

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 (faixa, álbum, artista, playlist)
  - limit (número, 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)
getTopItems
- Descrição: Obter os principais artistas ou faixas do usuário atual com base na afinidade calculada
- Parâmetros:
  - type (string): O tipo de entidade a retornar. Valores válidos: artists ou tracks
  - time_range (string, opcional): Período de tempo em que as afinidades são calculadas. Long_term ~1 ano de dados, medium_term é os últimos 6 meses, short_term é as últimas 4 semanas
  - limit (número, opcional): O número máximo de itens a retornar. Padrão: 20, mínimo: 1, máximo: 50
- Retorna: Lista de itens correspondentes com nome, IDs e detalhes adicionais
- Exemplo: getTopItems("artists", "short_term", 5)
getMyPlaylists
- Descrição: Obter uma lista das playlists de propriedade ou seguidas pelo usuário atual do Spotify
- Parâmetros:
  - limit (número, opcional): O número máximo de itens a retornar. Padrão: 20, mínimo: 1, máximo: 50
- Retorna: Lista de playlists correspondentes com nome, IDs e detalhes adicionais
- Exemplo: getMyPlaylists(25)
getPlaylistItems
- Descrição: Obter detalhes completos dos itens de uma playlist de propriedade de um usuário do Spotify
- Parâmetros:
  - playlist_id (string): O ID do Spotify da playlist
  - fields (string, opcional): Uma lista separada por vírgulas dos campos a retornar
  - limit (número, opcional): O número máximo de itens a retornar. Padrão: 20, mínimo: 1, máximo: 50
- Retorna: Lista de itens de playlist correspondentes com nome, IDs e detalhes adicionais
- Exemplo: getPlaylistItems("123")
getCurrentUserProfile
- Descrição: Obter informações detalhadas do perfil do usuário atual
- Parâmetros: Nenhum
- Retorna: Nome de exibição do usuário, ID, e-mail e número de seguidores
- Exemplo: getCurrentUserProfile()
getCurrentlyPlaying
- Descrição: Obter detalhes completos dos itens de uma playlist de propriedade de um usuário do Spotify
- Parâmetros: Nenhum
- Retorna: Retorna o nome do item atualmente em reprodução e detalhes acompanhantes
- Exemplo: getCurrentlyPlaying()
getRecentlyPlayedTracks
- Descrição: Obter detalhes completos dos itens de uma playlist de propriedade de um usuário do Spotify
- Parâmetros:
  - limit (número, opcional): O número máximo de itens a retornar. Padrão: 20, mínimo: 1, máximo: 50
- Retorna: Lista de nomes de faixas reproduzidas recentemente e informações adicionais
- Exemplo: getRecentlyPlayedTracks(20)
getUserQueue
- Descrição: Obter a lista de objetos que compõem a fila do usuário
- Parâmetros: Nenhum
- Retorna: Os nomes dos itens e informações adicionais na fila
- Exemplo: getUserQueue()

Operações de Escrita

startPlayback
- Descrição: Iniciar uma nova reprodução no dispositivo ativo
- Parâmetros:
  - device_id (string, opcional): O ID do dispositivo ao qual este comando se destina
  - context_uri (número, opcional): URI do Spotify do contexto a reproduzir. Contextos válidos são álbuns, artistas e playlists
  - type (número, opcional): O tipo a reproduzir. Tipos válidos são faixa, álbum, artista ou playlist
  - id (número, opcional): O ID do Spotify do item a reproduzir
- Retorna: Reprodução iniciada
- Exemplo: startPlayback()
resumePlayback
- Descrição: Retomar a reprodução no dispositivo ativo
- Parâmetros:
  - device_id (string, opcional): O ID do dispositivo ao qual este comando se destina
- Retorna: Reprodução retomada
- Exemplo: resumePlayback()
pausePlayback
- Descrição: Pausar a reprodução no dispositivo ativo
- Parâmetros:
  - device_id (string, opcional): O ID do dispositivo ao qual este comando se destina
- Retorna: Reprodução pausada
- Exemplo: pausePlayback()
addQueue
- Descrição: Adicionar um item para ser reproduzido em seguida na fila de reprodução
- Parâmetros:
  - uri (string): O URI do item a adicionar à fila. Deve ser um URI de faixa ou episódio
  - device_id (string, opcional): O ID do dispositivo ao qual este comando se destina
- Retorna: Adicionado à fila
- Exemplo: addQueue("123uri")
togglePlaybackShuffle
- Descrição: Alternar o modo aleatório (shuffle) para a reprodução do usuário
- Parâmetros:
  - state (booleano): Verdadeiro: Embaralhar a reprodução do usuário. Falso: Não embaralhar a reprodução do usuário
  - device_id (string, opcional): O ID do dispositivo ao qual este comando se destina
- Retorna: Modo aleatório alterado
- Exemplo: togglePlaybackShuffle(true)
createPlaylist
- Descrição: Criar uma playlist para um usuário do Spotify
- Parâmetros:
  - device_id (string): O ID do usuário do Spotify
  - name (string): O nome da sua nova playlist
  - public (booleano, opcional): O status público/privado da playlist
  - description (string, opcional): A descrição da playlist
- Retorna: Nova playlist criada
- Exemplo: createPlaylist("user123", "new playlist", true, "This is a new playlist")
addItemsToPlaylist
- Descrição: Adiciona um ou mais itens a uma playlist do usuário
- Parâmetros:
  - playlist_id (string): O ID do Spotify da playlist
  - uris (string, opcional): Uma lista separada por vírgulas de URIs do Spotify a adicionar, pode ser URIs de faixa ou episódio
  - types (booleano, opcional): Uma lista separada por vírgulas de tipos na mesma ordem que os IDs
  - ids (string, opcional): Uma lista separada por vírgulas de IDs na mesma ordem que os tipos
- Retorna: Itens adicionados à playlist
- Exemplo: createPlaylist("playlist123")
changePlaylistDetails
- Descrição: Alterar o nome e o estado público/privado de uma playlist
- Parâmetros:
  - playlist_id (string): O ID do Spotify da playlist
  - name (string, opcional): O novo nome da playlist
  - public (booleano, opcional): O novo status público/privado da playlist
  - description (string, opcional): Valor para a descrição da playlist
- Retorna: Detalhes da playlist alterados
- Exemplo: changePlaylistDetails("playlist123", "new new playlist")

Configuração

Pré-requisitos

Node.js v16+
Uma conta Spotify Premium
Um aplicativo de desenvolvedor Spotify registrado

Instalação

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

Criando um Aplicativo de Desenvolvedor Spotify

Acesse o Painel do Desenvolvedor Spotify
Faça login com sua conta Spotify
Clique no botão "Create an App"
Preencha o nome e a descrição do aplicativo
Aceite os Termos de Serviço e clique em "Create"
No painel do seu novo aplicativo, você verá seu Client ID
Clique em "Show Client Secret" para revelar seu Client Secret
Clique em "Edit Settings" e adicione um Redirect URI (por exemplo, http://localhost:8000/callback)
Salve suas alterações

Configuração da API do Spotify

Crie um arquivo .env.local na raiz do projeto (você pode copiar e modificar o exemplo fornecido):

SPOTIFY_CLIENT_ID='Your client_id'
SPOTIFY_CLIENT_SECRET='Your client_secret'
SPOTIFY_REDIRECT_URI='Your redirect_uri (i.e. http://127.0.0.1:8000/callback'

Certifique-se de que seu redirect_uri siga as Configurações do Desenvolvedor Spotify mais recentes.

Processo de Autenticação

A API do Spotify usa OAuth 2.0 para autenticação. Siga estas etapas para autenticar seu aplicativo:

Abra duas telas de terminal. Em uma, execute

redis-server

Na outra, execute

npm run auth

O script gerará uma URL de autorização. Abra esta URL no seu navegador.
Você será solicitado a fazer login no Spotify e autorizar seu aplicativo.
Após a autorização, o Spotify redirecionará você para o seu redirect URI especificado com um parâmetro code na URL.
O script de autenticação trocará automaticamente esse código por tokens de acesso e atualização.
Esses tokens serão salvos no banco de dados Redis e atualizados automaticamente quando chamados

Integração com o Claude Desktop

Para usar seu servidor MCP com o Claude Desktop, adicione-o à sua configuração do Claude:

{
  "mcpServers": {
    "spotify": {
      "command": "node",
      "args": ["MCP-Spotify/build/index.js"]
    }
  }
}

Se o Claude estiver em execução, reinicie o aplicativo e você deverá ver "spotify" como uma nova ferramenta