MCP Claude Spotify

MCP Claude Spotify

Uma integração que permite ao Claude Desktop interagir com o Spotify usando o Model Context Protocol (MCP).

Removido na versão 0.6.0 — get-recommendations. O Spotify descontinuou o /v1/recommendations em 27 de novembro de 2024, junto com artistas-relacionados, características-de-áudio, análise-de-áudio, playlists-em-destaque e URLs de prévia de 30 segundos. Aplicativos criados após essa data recebem 403 Forbidden, e aplicativos ainda em modo de desenvolvimento também perderam o acesso, então a ferramenta não poderia funcionar para praticamente ninguém. Use search-spotify e get-top-tracks em vez disso. Veja o anúncio do Spotify.

Recursos

• Autenticação do Spotify
• Busca por músicas, álbuns, artistas e playlists
• Controle de reprodução (tocar, pausar, próxima, anterior)
• Gerenciamento completo de playlists (criar, atualizar, excluir, reordenar músicas, gerenciar imagens de capa)
• Leia suas músicas mais tocadas e histórico de reprodução
• Acesse as músicas mais tocadas do usuário em diferentes períodos de tempo
• Veja músicas reproduzidas recentemente

Demonstração

Requisitos

• Node.js 20 ou superior
• Conta do Spotify
• Claude Desktop
• Credenciais da API do Spotify (Client ID e Client Secret)

Instalação

Instalando via Smithery

Para instalar o MCP Claude Spotify para Claude Desktop automaticamente via Smithery:

npx -y @smithery/cli@latest mcp add imprvhub/mcp-claude-spotify --client claude

Instalando Manualmente

1. Clone ou baixe este repositório:

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

2. Instale as dependências:

npm install

3. Compile o projeto (se quiser modificar o código-fonte):

npm run build

O repositório já inclui arquivos pré-compilados no diretório build, então você pode pular o passo 3 se não planeja modificar o código-fonte.

Configurando as Credenciais do Spotify

Para usar este MCP, você precisa obter as credenciais da API do Spotify:

1. Vá para o Painel do Desenvolvedor do Spotify
2. Faça login com sua conta do Spotify
3. Clique em "Create App" (Criar Aplicativo)
4. Preencha as informações do seu aplicativo:
   • Nome do aplicativo: "MCP Claude Spotify" (ou o que preferir)
   • Descrição do aplicativo: "Integração do Spotify para Claude Desktop"
   • Site: Você pode deixar em branco ou colocar qualquer URL
   • URI de redirecionamento: Importante - Adicione http://127.0.0.1:8888/callback
5. Aceite os termos e condições e clique em "Create" (Criar)
6. No painel do seu aplicativo, você verá o "Client ID"
7. Clique em "Show Client Secret" (Mostrar Client Secret) para revelar seu "Client Secret"

Salve essas credenciais, pois você precisará delas para a configuração.

Executando o Servidor MCP

Existem duas maneiras de executar o servidor MCP:

Opção 1: Autorizar uma vez pelo terminal (configuração inicial)

O Claude Desktop inicia sua própria cópia do servidor, então um servidor em execução no terminal não é o mesmo com o qual o Claude se comunica. A utilidade de executar no terminal é autorizar uma vez: com SPOTIFY_AUTO_AUTH=true e sem tokens armazenados, o servidor abre o login do Spotify no seu navegador assim que inicia.

SPOTIFY_CLIENT_ID=your_client_id \
SPOTIFY_CLIENT_SECRET=your_client_secret \
SPOTIFY_AUTO_AUTH=true \
node build/index.js

Aprove a solicitação no navegador. Quando o terminal exibir "Authorization complete" (Autorização concluída), interrompa o processo com Ctrl+C. O token é salvo em ~/.spotify-mcp/tokens.json, e a cópia que o Claude Desktop inicia irá utilizá-lo.

Você pode pular esta etapa completamente e pedir ao Claude para "autenticar com o Spotify" em vez disso, o que executa a ferramenta auth-spotify e abre a mesma página de login.

Opção 2: Início automático com o Claude Desktop (recomendado para uso regular)

O Claude Desktop pode iniciar automaticamente o servidor MCP quando necessário. Para configurar isso:

Configuração

O arquivo de configuração do Claude Desktop está localizado em:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Edite este arquivo para adicionar a configuração do MCP do Spotify. Se o arquivo não existir, crie-o:

{
  "mcpServers": {
    "spotify": {
      "command": "node",
      "args": ["ABSOLUTE_PATH_TO_DIRECTORY/mcp-claude-spotify/build/index.js"],
      "env": {
        "SPOTIFY_CLIENT_ID": "your_client_id_here",
        "SPOTIFY_CLIENT_SECRET": "your_client_secret_here"
      }
    }
  }
}

Importante: Substitua:

• ABSOLUTE_PATH_TO_DIRECTORY pelo caminho absoluto completo onde você instalou o MCP
  • Exemplo macOS/Linux: /Users/username/mcp-claude-spotify
  • Exemplo Windows: C:\\Users\\username\\mcp-claude-spotify
• your_client_id_here pelo Client ID que você obteve do Spotify
• your_client_secret_here pelo Client Secret que você obteve do Spotify

Se você já tem outros MCPs configurados, basta adicionar a seção "spotify" dentro do objeto "mcpServers".

Configurando scripts de início automático (Opcional)

Para uma experiência mais confiável, você pode configurar scripts de início automático:

@echo off
cd %~dp0
node build/index.js

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.spotify.mcp</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/node</string>
        <string>ABSOLUTE_PATH_TO_DIRECTORY/mcp-claude-spotify/build/index.js</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardErrorPath</key>
    <string>/tmp/spotify-mcp.err</string>
    <key>StandardOutPath</key>
    <string>/tmp/spotify-mcp.out</string>
    <key>EnvironmentVariables</key>
    <dict>
        <key>SPOTIFY_CLIENT_ID</key>
        <string>your_client_id_here</string>
        <key>SPOTIFY_CLIENT_SECRET</key>
        <string>your_client_secret_here</string>
    </dict>
</dict>
</plist>

[Unit]
Description=Spotify MCP Server for Claude Desktop
After=network.target

[Service]
Type=simple
ExecStart=/usr/bin/node ABSOLUTE_PATH_TO_DIRECTORY/mcp-claude-spotify/build/index.js
Restart=on-failure
Environment="SPOTIFY_CLIENT_ID=your_client_id_here"
Environment="SPOTIFY_CLIENT_SECRET=your_client_secret_here"

[Install]
WantedBy=default.target

systemctl --user enable spotify-mcp.service
systemctl --user start spotify-mcp.service

systemctl --user status spotify-mcp.service

Desenvolvimento

npm install
npm run build
npm test

Uso

1. Reinicie o Claude Desktop após modificar a configuração
2. No Claude, use o comando auth-spotify para iniciar o processo de autenticação
3. Uma janela do navegador será aberta para você autorizar o aplicativo
4. Faça login com sua conta do Spotify e autorize o aplicativo
5. Importante: Após a autenticação bem-sucedida, reinicie o Claude Desktop para inicializar corretamente o registro de ferramentas do MCP e o cache de token da sessão WebSocket
6. Após reiniciar, todas as ferramentas do MCP do Spotify estarão devidamente registradas e disponíveis para uso

O servidor MCP é executado como um processo filho gerenciado pelo Claude Desktop. Quando o Claude está em execução, ele inicia e gerencia automaticamente o processo do servidor Node.js com base na configuração em claude_desktop_config.json.

Notas de segurança

• A autorização é protegida contra CSRF. A URL de login carrega um valor aleatório de state que o callback verifica antes de trocar um código. Versões anteriores à 0.6.0 não enviavam state, então qualquer página aberta no seu navegador poderia acessar o callback de loopback e vincular uma conta diferente do Spotify.
• O arquivo de token é somente do proprietário. ~/.spotify-mcp/tokens.json contém um token de atualização de longa duração e agora é gravado com modo 600 em um diretório 700. Anteriormente, era criado com o modo padrão, deixando-o legível por todas as contas da máquina.
• Nada é encerrado para liberar a porta. Se a porta 8888 estiver ocupada, o servidor reporta o problema e para. Versões anteriores executavam lsof -i:8888 -t | xargs kill -9 (e um equivalente taskkill no Windows), encerrando à força qualquer processo não relacionado que ocupasse essa porta de desenvolvimento tão comum.
• IDs nos argumentos das ferramentas são validados. IDs de músicas, playlists e dispositivos vão para caminhos de API e strings de consulta, então apenas IDs simples do Spotify são aceitos; qualquer outra coisa é rejeitada antes de uma solicitação ser construída.
• O callback escuta apenas em loopback (127.0.0.1). O listener express anterior vinculava todas as interfaces de rede, então qualquer pessoa na mesma rede poderia acessar /login e /callback. Containers podem ampliar isso com AUTH_BIND_HOST=0.0.0.0.
• O servidor de callback é encerrado assim que a autorização é concluída, em vez de permanecer vinculado pelo resto da sessão.

Ferramentas Disponíveis

Autenticação

auth-spotify

Inicia o processo de autenticação do Spotify.

Busca

search-spotify

Busca por músicas, álbuns, artistas ou playlists.

Parâmetros:

• query: Texto da busca
• type: Tipo de busca (música, álbum, artista, playlist)
• limit: Número de resultados (1-10, padrão: 5)

Controle de Reprodução

get-current-playback

Obtém informações sobre o estado atual da reprodução.

play-track

Reproduz uma música específica em um dispositivo ativo.

Parâmetros:

• trackId: ID da música no Spotify
• deviceId: (Opcional) ID do dispositivo no Spotify para reproduzir

pause-playback

Pausa a reprodução atual.

next-track

Avança para a próxima música.

previous-track

Volta para a música anterior.

Gerenciamento de Playlists

get-user-playlists

Obtém uma lista das playlists do usuário.

Parâmetros:

• limit: (Opcional) Número de playlists a retornar (1-50, padrão: 20)
• offset: (Opcional) Índice da primeira playlist a retornar (padrão: 0)

create-playlist

Cria uma nova playlist para o usuário atual.

Parâmetros:

• name: Nome da playlist
• description: (Opcional) Descrição
• public: (Opcional) Se é pública ou privada

update-playlist

Atualiza o nome, descrição, status público/privado ou configuração colaborativa de uma playlist.

Parâmetros:

• playlistId: ID da playlist no Spotify
• name: (Opcional) Novo nome para a playlist
• description: (Opcional) Nova descrição para a playlist
• public: (Opcional) Se a playlist deve ser pública
• collaborative: (Opcional) Se a playlist deve ser colaborativa (é necessário definir público como falso primeiro)

delete-playlist

Deixa de seguir (remove) uma playlist da sua biblioteca. A playlist ainda existe no Spotify, mas não está mais na sua biblioteca.

Parâmetros:

• playlistId: ID da playlist no Spotify

get-playlist-tracks

Obtém as músicas de uma playlist com suporte a paginação.

Parâmetros:

• playlistId: ID da playlist no Spotify
• limit: (Opcional) Número de músicas a retornar (1-50, padrão: 20)
• offset: (Opcional) Índice da primeira música a retornar (padrão: 0)

add-tracks-to-playlist

Adiciona músicas a uma playlist.

Parâmetros:

• playlistId: ID da playlist
• trackIds: Matriz de IDs de músicas

remove-tracks-from-playlist

Remove músicas de uma playlist.

Parâmetros:

• playlistId: ID da playlist no Spotify
• trackIds: Matriz de IDs de músicas do Spotify a remover

reorder-playlist-tracks

Reordena músicas em uma playlist movendo um intervalo de músicas para uma nova posição.

Parâmetros:

• playlistId: ID da playlist no Spotify
• rangeStart: Posição da primeira música a mover
• insertBefore: Posição onde as músicas devem ser inseridas
• rangeLength: (Opcional) Número de músicas a mover (padrão: 1)

get-playlist-cover

Obtém a imagem de capa de uma playlist.

Parâmetros:

• playlistId: ID da playlist no Spotify

upload-playlist-cover

Envia uma imagem de capa personalizada para uma playlist (JPEG codificado em base64, máx. 256KB).

Parâmetros:

• playlistId: ID da playlist no Spotify
• imageBase64: Imagem JPEG codificada em base64

Descoberta e Histórico

get-top-tracks

Obtém as músicas mais tocadas do usuário em um intervalo de tempo especificado.

Parâmetros:

• limit: (Opcional) Número de músicas a retornar (1-50, padrão: 20)
• offset: (Opcional) Índice da primeira música a retornar (padrão: 0)
• time_range: (Opcional) Período de tempo para calcular a afinidade:
  • short_term: Aproximadamente as últimas 4 semanas
  • medium_term: Aproximadamente os últimos 6 meses (padrão)
  • long_term: Vários anos de dados

get-recently-played

Obtém as músicas reproduzidas recentemente pelo usuário. Parâmetros:

• limit: (Opcional) Número máximo de faixas a retornar (1-50, padrão: 20)
• before: (Opcional) Timestamp Unix em milissegundos. Retorna faixas reproduzidas antes deste horário
• after: (Opcional) Timestamp Unix em milissegundos. Retorna faixas reproduzidas depois deste horário

Solução de Problemas

Erro "Servidor desconectado"

Se você vir o erro "MCP Spotify: Server disconnected" no Claude Desktop:

1. Verifique se o servidor está em execução:

   • Abra um terminal e execute manualmente node build/index.js a partir do diretório do projeto
   • Se o servidor iniciar com sucesso, use o Claude mantendo este terminal aberto

2. Verifique sua configuração:

   • Certifique-se de que o caminho absoluto em claude_desktop_config.json está correto para o seu sistema
   • Verifique se você usou barras invertidas duplas (\\) para caminhos do Windows
   • Confirme que você está usando o caminho completo a partir da raiz do seu sistema de arquivos

3. Experimente a opção de inicialização automática:

   • Configure o script de inicialização automática para o seu sistema operacional conforme descrito na seção "Configurando scripts de inicialização automática"
   • Isso garante que o servidor esteja sempre em execução quando você precisar

O navegador não abre automaticamente

Se o navegador não abrir automaticamente durante a autenticação, visite manualmente: http://127.0.0.1:8888/login

Erro de autenticação

Certifique-se de ter configurado corretamente o URI de redirecionamento no seu painel do Spotify Developer: http://127.0.0.1:8888/callback

Erro de inicialização do servidor

Verifique se:

• As variáveis de ambiente estão configuradas corretamente no seu claude_desktop_config.json ou script de inicialização
• O Node.js está instalado e é compatível (v16+)
• As portas necessárias (8888) estão disponíveis e não bloqueadas por firewall
• Você tem permissão para executar o script no local especificado

Ferramentas não aparecem no Claude

Se as ferramentas do Spotify não aparecerem no Claude após a autenticação:

• Certifique-se de ter reiniciado o Claude Desktop após a autenticação bem-sucedida
• Verifique os logs do Claude Desktop para erros de comunicação MCP
• Garanta que o processo do servidor MCP está em execução (execute manualmente para confirmar)
• Verifique se o servidor MCP está corretamente registrado no registro MCP do Claude Desktop

Verificando se o servidor está em execução

Para verificar se o servidor está em execução:

• Windows: Abra o Gerenciador de Tarefas, vá para a aba "Detalhes" e procure por "node.exe"
• macOS/Linux: Abra o Terminal e execute ps aux | grep node

Se você não vir o servidor em execução, inicie-o manualmente ou use o método de inicialização automática.

Testes

Este projeto inclui testes automatizados para garantir a qualidade do código e a funcionalidade. A suíte de testes usa Jest com suporte a TypeScript e cobre:

• Validação de esquema Zod - verifica se todos os esquemas de entrada validam dados corretamente
• Interações com a API do Spotify - testa o tratamento de requisições e erros da API
• Funcionalidade do servidor MCP - garante o registro e execução adequados das ferramentas

Executando Testes

Primeiro, certifique-se de que todas as dependências de desenvolvimento estão instaladas:

npm install

Para executar todos os testes:

npm test

Para executar um arquivo de teste específico:

npm test -- --testMatch="**/tests/schemas.test.ts"

Se você encontrar problemas com módulos ESM, certifique-se de estar usando Node.js v16 ou superior e que a variável de ambiente NODE_OPTIONS inclui o sinalizador --experimental-vm-modules conforme configurado no package.json.

Estrutura de Testes

• tests/schemas.test.ts: Testes para esquemas de validação de entrada
• tests/spotify-api.test.ts: Testes para interações com a API do Spotify
• tests/server.test.ts: Testes para funcionalidade do servidor MCP

Adicionando Novos Testes

Ao adicionar novas funcionalidades, inclua testes correspondentes:

1. Para novos esquemas, adicione testes de validação em schemas.test.ts
2. Para funções da API do Spotify, adicione testes em spotify-api.test.ts
3. Para ferramentas MCP, adicione testes em server.test.ts

Todos os testes devem ser escritos usando Jest e o formato de módulo ESM com TypeScript.

Notas de Segurança

• Nunca compartilhe seu Client ID e Client Secret
• O token de acesso agora é armazenado no diretório inicial do usuário em ~/.spotify-mcp/tokens.json para permitir persistência entre sessões e múltiplas instâncias
• Nenhum dado do usuário é armazenado em disco

Revogando o Acesso do Aplicativo

Por razões de segurança, você pode querer revogar o acesso do aplicativo à sua conta do Spotify quando:

• Você não usa mais esta integração
• Você suspeita de acesso não autorizado
• Você está solucionando problemas de autenticação

Para revogar o acesso:

1. Vá para a sua página da conta do Spotify
2. Navegue até "Apps" no menu
3. Encontre "MCP Claude Spotify" (ou o nome que você escolheu para o seu aplicativo)
4. Clique em "REMOVER ACESSO"

Isso invalida imediatamente todos os tokens de acesso e atualização. Na próxima vez que você usar o comando auth-spotify, precisará autorizar o aplicativo novamente.

Contribuindo

Contribuições são bem-vindas! Aqui estão algumas diretrizes a seguir:

Fluxo de Desenvolvimento

1. Faça um fork do repositório
2. Crie um branch de funcionalidade (git checkout -b feature/amazing-feature)
3. Faça suas alterações
4. Execute os testes para garantir que passem (npm test)
5. Faça commit das suas alterações (git commit -m 'Add some amazing feature')
6. Envie para o branch (git push origin feature/amazing-feature)
7. Abra um Pull Request

Diretrizes de Estilo de Código

Este projeto segue os seguintes padrões de codificação:

• Use TypeScript com verificação estrita de tipos
• Siga o formato de módulo ESM
• Use 2 espaços para indentação
• Use camelCase para variáveis e funções
• Use PascalCase para classes e interfaces
• Documente funções com comentários JSDoc
• Mantenha o comprimento da linha abaixo de 100 caracteres

Estrutura do Projeto

O projeto segue esta estrutura:

mcp-claude-spotify/
├── src/               # Source code
├── build/             # Compiled JavaScript
├── tests/             # Test files
├── public/            # Public assets
└── ...

Processo de Pull Request

1. Certifique-se de que seu código segue as diretrizes de estilo
2. Atualize a documentação se necessário
3. Adicione testes para novas funcionalidades
4. Certifique-se de que todos os testes passem
5. Seu PR será revisado pelos mantenedores

Links Relacionados

• Model Context Protocol
• Documentação da API Web do Spotify
• Claude Desktop
• Série MCP

Licença

Este projeto é licenciado sob a Mozilla Public License 2.0 - consulte o arquivo LICENSE para detalhes.