MCP Spotify Server

# 🎵 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](https://developer.spotify.com/dashboard) 4. **ngrok** (para expor o servidor local) ## 🛠️ Instalação 1. **Clone o repositório:** ```bash git clone https://github.com/seu-usuario/MCPSpotify.git cd MCPSpotify ``` 2. **Instale as dependências:** ```bash npm install ``` 3. **Instale o ngrok:** **macOS (com Homebrew):** ```bash brew install ngrok/ngrok/ngrok ``` **Windows (com Chocolatey):** ```bash choco install ngrok ``` **Linux:** ```bash # 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 [site oficial](https://ngrok.com/download)** 4. **Configure as variáveis de ambiente:** ```bash cp env.example .env ``` 5. **Edite o arquivo `.env` com suas credenciais:** ```env 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:** ```bash cp configs/claude-desktop.example.json ~/.claude-desktop/config.json # Edite o arquivo com seu caminho e credenciais ``` **Para Cursor:** ```bash cp configs/cursor.example.json ~/.cursor/mcp.json # Edite o arquivo com seu caminho e credenciais ``` **Para outros clientes MCP:** ```bash 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](https://developer.spotify.com/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](https://ngrok.com) e crie uma conta gratuita - Isso permite URLs estáveis e remove limitações de tempo ### 2. Configure o ngrok ```bash # Autentique sua conta (opcional) ngrok config add-authtoken SEU_TOKEN_AQUI # Exponha a porta 8080 ngrok http 8080 ``` ### 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`: ```env SPOTIFY_REDIRECT_URI=https://abc123.ngrok.io/callback ``` ### 4. Inicie o servidor ```bash # Em um terminal, mantenha o ngrok rodando ngrok http 8080 # Em outro terminal, inicie o servidor npm run dev ``` ## 🚀 Uso ### Desenvolvimento ```bash # Terminal 1: Inicie o ngrok ngrok http 8080 # Terminal 2: Inicie o servidor npm run dev ``` ### Produção ```bash npm run build npm start ``` ## 🎯 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) ```json { "name": "spotify_auth", "arguments": {} } ``` 2) Depois de autorizar no Spotify, copie o `code` retornado e finalize: ```json { "name": "spotify_set_tokens", "arguments": { "code": "SEU_CODE_AQUI" } } ``` ### Buscar uma música ```json { "name": "spotify_search", "arguments": { "query": "Bohemian Rhapsody", "type": "track", "limit": 5 } } ``` ### Tocar uma música ```json { "name": "spotify_play", "arguments": { "track_id": "4uLU6hMCjMI75M1A2tKUQC" } } ``` ### Buscar playlists ```json { "name": "spotify_playlists", "arguments": { "limit": 10 } } ``` ## 🔒 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](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.