MCPSpotify by fborello - MCP 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

Node.js (versão 18 ou superior)
Conta Spotify (Premium recomendado para funcionalidade completa)
Aplicação Spotify registrada no Spotify Developer Dashboard
ngrok (para expor o servidor local)

🛠️ Instalação

Clone o repositório:

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

Instale as dependências:
```
npm install
```

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 site oficial

Configure as variáveis de ambiente:
```
cp env.example .env
```

Edite o arquivo .env com suas credenciais:

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

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

Acesse o Spotify Developer Dashboard
Clique em "Create App"
Preencha os dados:
- App name: MCP Spotify Server
- App description: Servidor MCP para integração com Spotify
Após criar, copie o Client ID e Client Secret
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

# Autentique sua conta (opcional)
ngrok config add-authtoken SEU_TOKEN_AQUI

# Exponha a porta 8080
ngrok http 8080

3. Atualize a Redirect URI

Copie a URL HTTPS fornecida pelo ngrok (ex: https://abc123.ngrok.io)
No Spotify Dashboard, adicione https://abc123.ngrok.io/callback nas Redirect URIs

Atualize seu arquivo .env:

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

4. Inicie o servidor

# Em um terminal, mantenha o ngrok rodando
ngrok http 8080

# Em outro terminal, inicie o servidor
npm run dev

🚀 Uso

Desenvolvimento

# Terminal 1: Inicie o ngrok
ngrok http 8080

# Terminal 2: Inicie o servidor
npm run dev

Produção

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

Iniciar o login (vai abrir o navegador)

{
  "name": "spotify_auth",
  "arguments": {}
}

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

{
  "name": "spotify_set_tokens",
  "arguments": { "code": "SEU_CODE_AQUI" }
}

Buscar uma música

{
  "name": "spotify_search",
  "arguments": {
    "query": "Bohemian Rhapsody",
    "type": "track",
    "limit": 5
  }
}

Tocar uma música

{
  "name": "spotify_play",
  "arguments": {
    "track_id": "4uLU6hMCjMI75M1A2tKUQC"
  }
}

Buscar playlists

{
  "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 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.