🎵 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

Related MCP server: Spotify MCP Node Server

📋 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": {}
}

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