Vulpes Spotify

Interaja com o Spotify para pesquisar e reproduzir faixas usando um assistente de IA.

Documentação

Servidor MCP Vulpes Spotify

Um servidor Model Context Protocol (MCP) que permite que assistentes de IA como o Claude interajam com o Spotify, permitindo que eles pesquisem e reproduzam faixas.

Recursos

Pesquise faixas por artista, título ou qualquer consulta
Reproduza faixas diretamente no seu dispositivo Spotify ativo
Obtenha informações sobre a faixa que está tocando atualmente
Encontre dispositivos de reprodução Spotify disponíveis
Funcionalidade combinada de pesquisa e reprodução
Liste as playlists do usuário no Spotify
Veja as faixas dentro das playlists
Reproduza playlists (com modo aleatório opcional)
Encontre e reproduza playlists pelo nome

Requisitos

Node.js (v16+)
Conta de Desenvolvedor Spotify
Conta Spotify Premium (para funcionalidade de reprodução)
Um cliente compatível com MCP (por exemplo, Claude Desktop)

Instalação

Instalando via Smithery

Para instalar o Servidor Vulpes Spotify para Claude Desktop automaticamente via Smithery:

npx -y @smithery/cli install @ejfox/vulpes-spotify-mcp --client claude

Instalação Manual

Clone este repositório:

git clone https://github.com/yourusername/spotify-mcp.git
cd spotify-mcp

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

Crie um arquivo .env com suas credenciais da API do Spotify:

SPOTIFY_CLIENT_ID=your_client_id
SPOTIFY_CLIENT_SECRET=your_client_secret
SPOTIFY_REDIRECT_URI=http://localhost:8888

# Optional: For playback control
SPOTIFY_REFRESH_TOKEN=your_refresh_token

Você pode obter seu Client ID e Secret no Painel do Desenvolvedor Spotify.

Gere um token de atualização (necessário para controle de reprodução):

Existem duas maneiras de obter um token de atualização:

Opção 1: Use o script integrado
```
npm run get-token
```
Isso iniciará um servidor local e fornecerá instruções no terminal.

Opção 2: Use o script simples (se a opção 1 não funcionar)
```
node src/simple-auth.js
```
Isso fornecerá uma URL para abrir no seu navegador. Após autorizar, você será redirecionado para uma URL. Copie essa URL de volta para o terminal, e ele mostrará um comando curl para obter o token de atualização.

Escopos necessários (já incluídos nos scripts):
- user-read-playback-state
- user-modify-playback-state
- user-read-currently-playing
- playlist-read-private
- playlist-read-collaborative
Adicione o token de atualização ao seu arquivo .env:
```
SPOTIFY_REFRESH_TOKEN=your_refresh_token
```
Compile o projeto:
```
npm run build
```

Uso com Claude Desktop

Primeiro, certifique-se de que o Spotify esteja aberto e reproduzindo no seu dispositivo

Adicione este servidor à configuração do seu Claude Desktop:

Edite seu arquivo claude_desktop_config.json (normalmente em ~/Library/Application Support/Claude/ no macOS ou %APPDATA%\\Claude\\ no Windows):

{
  "mcpServers": {
    "spotify": {
      "command": "node",
      "args": ["/absolute/path/to/vulpes-spotify-mcp/dist/index.js"],
      "env": {
        "SPOTIFY_CLIENT_ID": "your_client_id",
        "SPOTIFY_CLIENT_SECRET": "your_client_secret",
        "SPOTIFY_REDIRECT_URI": "http://localhost:8888",
        "SPOTIFY_REFRESH_TOKEN": "your_refresh_token"
      }
    }
  }
}

Certifique-se de substituir /absolute/path/to/vulpes-spotify-mcp pelo caminho real do seu projeto.

Reinicie o Claude Desktop
Agora você deve ver as ferramentas do Spotify disponíveis ao clicar no ícone de martelo no Claude Desktop

Ferramentas Disponíveis

spotify-search: Pesquise faixas por consulta
spotify-play: Reproduza uma faixa específica por ID ou URI
spotify-currently-playing: Obtenha informações sobre a faixa que está tocando atualmente
spotify-devices: Liste os dispositivos de reprodução Spotify disponíveis
spotify-search-and-play: Pesquise uma faixa e reproduza automaticamente o melhor resultado
spotify-playlists: Obtenha uma lista das playlists do usuário no Spotify
spotify-playlist-tracks: Obtenha faixas de uma playlist específica
spotify-play-playlist: Reproduza uma playlist específica (com aleatório opcional)
spotify-find-playlist: Encontre uma playlist pelo nome e reproduza-a (recomendado para uso com IA)

Solução de Problemas

"Nenhum dispositivo ativo encontrado": Certifique-se de que o Spotify esteja aberto e reproduzindo em pelo menos um dos seus dispositivos
"Permissões ausentes": Seu token de atualização pode não ter os escopos necessários
"Não é premium": O controle de reprodução requer uma conta Spotify Premium
"Problemas com o token de atualização": Se o seu token expirar, gere um novo usando as etapas na seção de instalação

Notas Importantes

Sempre certifique-se de que o Spotify esteja aberto em pelo menos um dispositivo antes de usar os controles de reprodução
O token de atualização no seu arquivo .env e na configuração do Claude Desktop devem corresponder
Após fazer alterações na sua configuração, reinicie o Claude Desktop

Licença

MIT