🎵 MCP Spotify Server

Um servidor MCP (Model Context Protocol) que permite interagir com o Spotify através de LLMs. Este servidor fornece ferramentas para buscar música, controlar reprodução, gerenciar playlists e muito mais.

🚀 Funcionalidades

• Autenticação OAuth2 com Spotify

• Busca por músicas, artistas, álbuns e playlists

• Controle de reprodução (tocar, pausar, próximo, anterior)

• Informações da música atual

• Gerenciamento de dispositivos

• Listagem e reprodução de playlists

📋 Pré-requisitos

1. Node.js (versão 18 ou superior)

2. Conta Spotify (Premium recomendado para funcionalidade completa)

3. Aplicação Spotify registrada no Spotify Developer Dashboard

4. ngrok (para expor o servidor local)

🛠️ Instalação

1. Clone o repositório:

   git clone https://github.com/seu-usuario/MCPSpotify.git cd MCPSpotify

2. Instale as dependências:

   npm install

3. Instale o ngrok:

   macOS (com Homebrew):

   brew install ngrok/ngrok/ngrok

   Windows (com Chocolatey):

   choco install ngrok

   Linux:

   # Baixe o binário do site oficial curl -s https://ngrok-agent.s3.amazonaws.com/ngrok.asc | sudo tee /etc/apt/trusted.gpg.d/ngrok.asc >/dev/null echo "deb https://ngrok-agent.s3.amazonaws.com buster main" | sudo tee /etc/apt/sources.list.d/ngrok.list sudo apt update && sudo apt install ngrok

   Ou baixe diretamente do

4. Configure as variáveis de ambiente:

   cp env.example .env

5. Edite o arquivo

   SPOTIFY_CLIENT_ID=seu_client_id_aqui SPOTIFY_CLIENT_SECRET=seu_client_secret_aqui SPOTIFY_REDIRECT_URI=http://localhost:3000/callback

6. Configure o MCP (opcional):

   Para Claude Desktop:

   cp configs/claude-desktop.example.json ~/.claude-desktop/config.json # Edite o arquivo com seu caminho e credenciais

   Para Cursor:

   cp configs/cursor.example.json ~/.cursor/mcp.json # Edite o arquivo com seu caminho e credenciais

   Para outros clientes MCP:

   cp mcp-config.example.json mcp-config.json # Edite o arquivo com seu caminho e credenciais

🔧 Configuração do Spotify

1. Acesse o Spotify Developer Dashboard

2. Clique em "Create App"

3. Preencha os dados:

   • App name: MCP Spotify Server

   • App description: Servidor MCP para integração com Spotify

4. Após criar, copie o Client ID e Client Secret

5. Clique em "Edit Settings" e adicione http://localhost:3000/callback nas Redirect URIs

🌐 Configuração do ngrok

Para que o OAuth do Spotify funcione corretamente, você precisa expor seu servidor local para a internet. O ngrok é a ferramenta recomendada para isso.

1. Crie uma conta no ngrok (opcional mas recomendado)

• Acesse ngrok.com e crie uma conta gratuita

• Isso permite URLs estáveis e remove limitações de tempo

2. Configure o ngrok

3. Atualize a Redirect URI

1. Copie a URL HTTPS fornecida pelo ngrok (ex: https://abc123.ngrok.io)

2. No Spotify Dashboard, adicione https://abc123.ngrok.io/callback nas Redirect URIs

3. Atualize seu arquivo .env:

   SPOTIFY_REDIRECT_URI=https://abc123.ngrok.io/callback

4. Inicie o servidor

🚀 Uso

Desenvolvimento

Produção

🎯 Ferramentas Disponíveis

Autenticação

• spotify_auth - Inicia o processo de autenticação

• spotify_set_tokens - Finaliza a autenticação com o code de retorno

Busca

• spotify_search - Busca por músicas, artistas, álbuns ou playlists

Controle de Reprodução

• spotify_play - Toca uma música específica

• spotify_pause - Pausa a reprodução

• spotify_resume - Retoma a reprodução

• spotify_next - Pula para a próxima música

• spotify_previous - Volta para a música anterior

Informações

• spotify_current_playing - Obtém informações sobre a música atual

• spotify_devices - Lista dispositivos disponíveis

• spotify_playlists - Lista playlists do usuário

Playlists

• spotify_play_playlist - Toca uma playlist específica

📝 Exemplos de Uso

Fluxo de Autenticação

1. Iniciar o login (vai abrir o navegador)

2. Depois de autorizar no Spotify, copie o code retornado e finalize:

Buscar uma música

Tocar uma música

Buscar playlists

🔒 Segurança

• As credenciais do Spotify são armazenadas apenas localmente

• Os tokens de acesso são renovados automaticamente

• Nenhuma informação é enviada para servidores externos (exceto Spotify)

🐛 Solução de Problemas

Erro de Autenticação

• Verifique se as credenciais no .env estão corretas

• Confirme se a Redirect URI está configurada no Spotify Dashboard

• Certifique-se de que o ngrok está rodando e a URL está atualizada no .env

• Verifique se a URL do ngrok no Spotify Dashboard corresponde à URL no arquivo .env

Dispositivo Não Encontrado

• Certifique-se de que o Spotify está aberto em algum dispositivo

• Verifique se o dispositivo está ativo na sua conta Spotify

Erro de Permissões

• Algumas funcionalidades requerem Spotify Premium

• Verifique se todas as permissões foram concedidas durante a autenticação

Problemas com ngrok

• URL muda a cada reinicialização: Use uma conta ngrok gratuita para URLs estáveis

• Erro de conexão: Verifique se o ngrok está rodando na porta correta (3000)

• Timeout: Certifique-se de que o servidor está rodando antes de iniciar o ngrok

• URL não acessível: Verifique se o firewall não está bloqueando a conexão

📄 Licença

MIT License - veja o arquivo LICENSE para detalhes.

🤝 Contribuição

Contribuições são bem-vindas! Sinta-se à vontade para abrir issues e pull requests.

📞 Suporte

Se você encontrar problemas ou tiver dúvidas, abra uma issue no repositório.