Spotify

Conecta sua conta do Spotify a ferramentas de IA, permitindo acesso à sua biblioteca musical, playlists e controles de reprodução.

GitHub
2
Experimente este MCPPatrocinado

Documentação

Servidor MCP do Spotify

Conecte sua conta do Spotify a ferramentas de IA e automatize sua experiência musical com o Model Context Protocol (MCP).

O Servidor MCP do Spotify implementa o Model Context Protocol para conectar sua conta do Spotify a ferramentas com tecnologia de IA, como Cursor, Claude, VS Code e outras. Ele permite que modelos de IA pesquisem, analisem e gerenciem sua biblioteca musical, playlists e reprodução do Spotify por meio de instruções em linguagem natural.

✨ Principais Recursos

  • 🎵 Pesquisa e Descoberta de Música: Encontre faixas, álbuns, artistas, playlists, programas e episódios
  • 📝 Gerenciamento de Playlists: Visualize, crie, atualize, reordene e gerencie playlists
  • 📚 Acesso à Biblioteca do Usuário: Acesse e modifique suas faixas, álbuns e programas salvos
  • 🎯 Recomendações Personalizadas: Obtenha sugestões musicais baseadas no seu gosto
  • 📊 Análise de Áudio: Recupere características de áudio (dançabilidade, energia, ritmo, etc.) das faixas
  • 🎧 Controle de Reprodução: (Somente Premium) Reproduzir, pausar, pular e controlar dispositivos de reprodução
  • 📈 Insights do Usuário: Visualize suas faixas, artistas e histórico de audição mais tocados
  • 🔄 Gerenciamento de Fila: Adicione faixas à sua fila e visualize as próximas músicas
  • 📱 Gerenciamento de Dispositivos: Transfira a reprodução entre dispositivos

🚀 Guia de Início Rápido

Pré-requisitos

  • Uma conta do Spotify (Premium é necessária para controle de reprodução)
  • Credenciais da API do Spotify (veja abaixo)
  • Node.js 18 ou mais recente

Passo 1: Obtenha as Credenciais da API do Spotify

  1. Acesse o Painel do Desenvolvedor do Spotify
  2. Crie um novo aplicativo
  3. Anote seu Client ID e Client Secret
  4. Defina o Redirect URI para: http://127.0.0.1:8000/callback

Passo 2: Configure as Variáveis de Ambiente

Crie um arquivo .env na raiz do seu projeto:

SPOTIFY_CLIENT_ID=your-client-id
SPOTIFY_CLIENT_SECRET=your-client-secret
SPOTIFY_REDIRECT_URI=http://127.0.0.1:8000/callback

Nota: Você não precisa mais obter tokens de acesso manualmente! O servidor cuidará do fluxo OAuth automaticamente.

Passo 3: Instale e Execute

# Install dependencies
npm install

# Build the server
npm run build

# Start the server
npm start

Passo 4: Conecte-se pela Sua Ferramenta de IA

Adicione esta configuração ao seu aplicativo compatível com MCP (exemplo para Cursor):

{
  "mcpServers": {
    "spotify": {
      "command": "npx",
      "args": ["-y", "@tdp2003/spotify-mcp@latest"],
      "env": {
        "SPOTIFY_CLIENT_ID": "your-client-id",
        "SPOTIFY_CLIENT_SECRET": "your-client-secret",
        "SPOTIFY_REDIRECT_URI": "http://127.0.0.1:8000/callback"
      }
    }
  }
}

Passo 5: Complete a Autorização

  1. Chame a ferramenta get_initial_context no seu aplicativo de IA
  2. Se ainda não estiver autorizado, você receberá uma URL de autorização
  3. Abra a URL no seu navegador e faça login no Spotify
  4. Autorize o aplicativo — você será redirecionado automaticamente
  5. Chame get_initial_context novamente para confirmar a conexão

🛠️ Ferramentas Disponíveis

⚠️ Importante: Sempre chame get_initial_context primeiro para inicializar sua conexão com o Spotify antes de usar qualquer outra ferramenta.

🔧 Contexto e Configuração

get_initial_context

Primeiro passo obrigatório — Inicializa sua conexão com o Spotify e fornece instruções de uso. Esta ferramenta deve ser chamada antes de qualquer outra operação.

O que ela faz:

  • Valida suas credenciais da API do Spotify
  • Inicia o fluxo OAuth, se necessário
  • Recupera seu perfil de usuário e informações da conta
  • Fornece status da conexão e recursos disponíveis
  • Retorna instruções de uso para o assistente de IA

📝 Operações de Playlist

get_user_playlists

Recupera playlists do usuário atual ou de um usuário específico.

Parâmetros:

  • limit (opcional): Número de playlists a retornar (1-50, padrão: 20)
  • offset (opcional): Índice da primeira playlist a retornar (padrão: 0)
  • userId (opcional): ID do usuário para obter playlists (padrão: usuário atual)

Retorna: Metadados da playlist, incluindo nome, descrição, contagem de faixas, configurações de privacidade e informações do proprietário.

create_playlist

Cria uma nova playlist com configurações personalizáveis.

Parâmetros:

  • name (obrigatório): Nome da playlist
  • description (opcional): Descrição da playlist
  • public (opcional): Se a playlist é pública (padrão: false)
  • collaborative (opcional): Se a playlist é colaborativa (padrão: false)
  • userId (opcional): ID do usuário para criar a playlist (padrão: usuário atual)

Retorna: Detalhes da playlist criada, incluindo URI e ID do Spotify.

update_playlist_details

Atualiza metadados da playlist, incluindo nome, descrição, configurações de privacidade e status colaborativo.

Parâmetros:

  • playlistId (obrigatório): ID da playlist no Spotify
  • name (opcional): Novo nome da playlist
  • description (opcional): Nova descrição da playlist
  • public (opcional): Nova configuração pública/privada
  • collaborative (opcional): Nova configuração colaborativa

Retorna: Detalhes atualizados da playlist com resumo das alterações.

add_tracks_to_playlist

Adiciona faixas a uma playlist com controle preciso de posição.

Parâmetros:

  • playlistId (obrigatório): ID da playlist no Spotify
  • uris (obrigatório): Matriz de URIs de faixas do Spotify (máx. 100)
  • position (opcional): Posição para inserir as faixas (padrão: final)

Retorna: Confirmação com ID do snapshot e contagem atualizada de faixas.

remove_tracks_from_playlist

Remove faixas de uma playlist com controle de precisão.

Parâmetros:

  • playlistId (obrigatório): ID da playlist no Spotify
  • tracks (obrigatório): Matriz de objetos de faixa com URIs e posições opcionais
  • snapshot_id (opcional): ID do snapshot da playlist para segurança de concorrência

Retorna: Confirmação com ID do snapshot e detalhes da remoção.

reorder_playlist_tracks

Reordena faixas dentro de uma playlist movendo um intervalo de faixas para uma nova posição.

Parâmetros:

  • playlistId (obrigatório): ID da playlist no Spotify
  • range_start (obrigatório): Posição inicial das faixas a mover
  • range_length (obrigatório): Número de faixas a mover
  • insert_before (obrigatório): Posição para onde mover as faixas
  • snapshot_id (opcional): ID do snapshot da playlist para segurança de concorrência

Retorna: Confirmação com ID do snapshot e detalhes da reordenação.

🔍 Pesquisa e Descoberta de Música

search

Pesquisa no catálogo do Spotify por álbuns, artistas, faixas, playlists, programas e episódios.

Parâmetros:

  • query (obrigatório): String de consulta de pesquisa
  • type (opcional): Filtro de tipo de conteúdo (track, album, artist, playlist, show, episode)
  • limit (opcional): Número de resultados (1-50, padrão: 20)
  • offset (opcional): Deslocamento de resultados (padrão: 0)
  • market (opcional): Código do país para resultados específicos do mercado

Retorna: Metadados detalhados para cada tipo de resultado com informações de paginação.

get_new_releases

Obtém novos lançamentos de álbuns disponíveis no Spotify.

Parâmetros:

  • limit (opcional): Número de lançamentos (1-50, padrão: 20)
  • offset (opcional): Deslocamento de resultados (padrão: 0)
  • country (opcional): Código do país para lançamentos regionais

Retorna: Álbuns lançados recentemente com informações do artista, datas de lançamento e metadados.

get_featured_playlists

Obtém playlists em destaque da equipe editorial do Spotify.

Parâmetros:

  • limit (opcional): Número de playlists (1-50, padrão: 20)
  • offset (opcional): Deslocamento de resultados (padrão: 0)
  • country (opcional): Código do país para conteúdo regional
  • locale (opcional): Idioma/localidade para descrições

Retorna: Playlists selecionadas em destaque no Spotify com descrições e metadados.

👤 Biblioteca do Usuário e Insights

get_user_top_items

Obtém os principais artistas ou faixas do usuário atual com base na afinidade calculada.

Parâmetros:

  • type (obrigatório): Tipo de item ('artists' ou 'tracks')
  • time_range (opcional): Intervalo de tempo ('short_term' ~4 semanas, 'medium_term' ~6 meses, 'long_term' ~1 ano)
  • limit (opcional): Número de itens (1-50, padrão: 20)
  • offset (opcional): Deslocamento de resultados (padrão: 0)

Retorna: Principais itens do usuário com pontuações de popularidade e metadados.

🎧 Controle de Reprodução (Somente Premium)

Nota: Estas ferramentas exigem uma conta Spotify Premium

get_current_playback

Obtém informações sobre a faixa em reprodução e o dispositivo atual.

Retorna: Estado atual da reprodução, incluindo faixa, dispositivo e informações da fila.

playback_control

Controla a reprodução (reproduzir, pausar, pular, volume).

Parâmetros:

  • action (obrigatório): Ação de reprodução (play, pause, next, previous, volume)
  • device_id (opcional): ID do dispositivo de destino
  • volume_percent (opcional): Nível de volume (0-100, para ação de volume)

Retorna: Confirmação da ação de reprodução.

queue_management

Adiciona faixas à fila e visualiza as próximas faixas.

Parâmetros:

  • action (obrigatório): Ação de fila ('add' ou 'get')
  • uris (opcional): URIs de faixas para adicionar (para ação 'add')
  • device_id (opcional): ID do dispositivo de destino

Retorna: Informações da fila ou confirmação da adição de faixas.

device_management

Transfere a reprodução entre dispositivos.

Parâmetros:

  • device_id (obrigatório): ID do dispositivo de destino
  • play (opcional): Se deve iniciar a reprodução na transferência (padrão: false)

Retorna: Confirmação da transferência de dispositivo.

📊 Análise de Áudio

get_audio_features

Recupera características de áudio das faixas.

Parâmetros:

  • track_ids (obrigatório): Matriz de IDs de faixas do Spotify

Retorna: Características de áudio, incluindo:

  • Dançabilidade: Quão adequada para dançar (0.0-1.0)
  • Energia: Intensidade e potência (0.0-1.0)
  • Fala: Presença de palavras faladas (0.0-1.0)
  • Acústica: Se a faixa é acústica (0.0-1.0)
  • Instrumentalidade: Se a faixa não tem vocais (0.0-1.0)
  • Ao vivo: Presença de público (0.0-1.0)
  • Valência: Positividade/felicidade musical (0.0-1.0)
  • Tempo: Velocidade em batidas por minuto (BPM)

⚙️ Variáveis de Ambiente

VariávelDescriçãoObrigatória
SPOTIFY_CLIENT_IDID do cliente do Spotify✅
SPOTIFY_CLIENT_SECRETSegredo do cliente do Spotify✅
SPOTIFY_REDIRECT_URIURI de redirecionamento do Spotify (use http://127.0.0.1:8000/callback)✅
SPOTIFY_API_TOKENToken de acesso do Spotify (obtido via OAuth)❌*
SPOTIFY_REFRESH_TOKENToken de atualização do Spotify (obtido via OAuth)❌*
MAX_TOOL_TOKEN_OUTPUTSaída máxima de tokens para respostas de ferramentas (padrão 50000)❌

*Estes tokens são obtidos automaticamente por meio do fluxo OAuth quando você usa o servidor pela primeira vez.

👥 Papéis de Usuário

  • developer: Acesso total a todas as ferramentas e recursos
  • editor: Restrito a ferramentas focadas em conteúdo (sem recursos administrativos)

Defina o papel na configuração do seu cliente MCP, se suportado.

📦 Configuração do Ambiente Node.js

Se você usa um gerenciador de versão do Node (nvm, mise, fnm, etc.), talvez seja necessário criar links simbólicos para que os servidores MCP possam acessar o Node.js:

sudo ln -sf "$(which node)" /usr/local/bin/node && sudo ln -sf "$(which npx)" /usr/local/bin/npx

Atualize esses links simbólicos se você mudar as versões do Node. Remova-os com:

sudo rm /usr/local/bin/node /usr/local/bin/npx

💻 Desenvolvimento

Instale as dependências:

npm install

Compile e execute em modo de desenvolvimento:

npm run dev

Compile o servidor:

npm run build

Execute o servidor compilado:

npm start

🧑‍💻 Depuração

Você pode usar o inspetor MCP para depuração:

npx @modelcontextprotocol/inspector -e SPOTIFY_CLIENT_ID=... -e SPOTIFY_CLIENT_SECRET=... -e SPOTIFY_REDIRECT_URI=... -e SPOTIFY_API_TOKEN=... -e SPOTIFY_REFRESH_TOKEN=... node path/to/build/index.js

Isso fornece uma interface web para inspecionar e testar as ferramentas disponíveis.

Fluxo OAuth

O fluxo OAuth foi aprimorado com as seguintes melhorias de segurança e usabilidade:

Melhorias de Segurança

  • Validação de estado: Usa parâmetros de estado aleatórios criptograficamente seguros para prevenir ataques CSRF
  • Validação da URI de redirecionamento: Garante que a URI de redirecionamento use localhost/127.0.0.1 para troca automática de tokens
  • Tratamento adequado de erros: Tratamento abrangente de erros para todos os cenários de falha do OAuth

Melhorias de Usabilidade

  • Abertura automática do navegador: Abre automaticamente a URL de autorização no seu navegador padrão
  • Melhor feedback ao usuário: Mensagens de erro claras e atualizações de status durante todo o processo
  • Desligamento gracioso do servidor: Fecha corretamente o servidor de callback OAuth após a conclusão

Usando o Auxiliar OAuth

O script oauth-helper.js fornece uma maneira independente de obter tokens do Spotify:

node src/utils/oauth-helper.js

Isto irá:

  1. Validar a configuração do seu ambiente
  2. Iniciar um servidor de callback local
  3. Abrir automaticamente o seu navegador na página de autorização do Spotify
  4. Lidar com o callback e trocar o código por tokens
  5. Exibir os tokens para você adicionar ao seu arquivo .env

Variáveis de Ambiente

Certifique-se de que o seu URI de redirecionamento está configurado corretamente:

SPOTIFY_REDIRECT_URI=http://127.0.0.1:8000/callback

O URI de redirecionamento deve usar localhost ou 127.0.0.1 para que a troca automática de tokens funcione corretamente.

Licença

MIT