🎵 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/fborello/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 site oficial

4. Configure as variáveis de ambiente:

   cp env.example .env
   

5. 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
   

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

# 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:

   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

1. Iniciar o login (vai abrir o navegador)

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

1. 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
  }
}

✅ Validar o Servidor MCP

Para verificar se o servidor está configurado corretamente:

npm run validate

Este comando irá:

• ✅ Verificar se o build existe
• ✅ Validar o arquivo .env
• ✅ Checar variáveis de ambiente
• ✅ Mostrar a configuração correta para o cliente MCP

Configuração do Cliente MCP

Após validar, você pode usar a configuração sugerida pelo script no seu arquivo de configuração do cliente:

Para Cursor (~/.cursor/mcp.json):

{
  "mcpServers": {
    "spotify": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "/caminho/para/MCPSpotify",
      "env": {
        "SPOTIFY_CLIENT_ID": "seu_client_id",
        "SPOTIFY_CLIENT_SECRET": "seu_client_secret",
        "SPOTIFY_REDIRECT_URI": "sua_redirect_uri"
      }
    }
  }
}

Para Claude Desktop (~/.claude-desktop/config.json):

{
  "mcpServers": {
    "spotify": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "/caminho/para/MCPSpotify",
      "env": {
        "SPOTIFY_CLIENT_ID": "seu_client_id",
        "SPOTIFY_CLIENT_SECRET": "seu_client_secret",
        "SPOTIFY_REDIRECT_URI": "sua_redirect_uri"
      }
    }
  }
}

Importante:

• Use node dist/index.js (não tsx src/index.ts) para produção
• Certifique-se de que o caminho cwd está correto
• Inclua as variáveis de ambiente no arquivo de configuração
• Após alterar a configuração, reinicie o cliente MCP

🔒 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

Erro "Cannot find module" ou caminho incorreto

• Erro: Cannot find module '/Users/.../src/index.ts'
• Solução: Use node dist/index.js ao invés de tsx src/index.ts no arquivo de configuração do MCP
• Execute npm run build antes de usar o servidor
• Certifique-se de que o cwd no arquivo de configuração aponta para o diretório correto do projeto
• Execute npm run validate para gerar a configuração correta

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.