Content
# 🎵 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/fborello/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
}
}
```
## ✅ Validar o Servidor MCP
Para verificar se o servidor está configurado corretamente:
```bash
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`):
```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`):
```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](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.
