auxcord-mcp

Servidor MCP do Spotify

Um servidor Model Context Protocol (MCP) que dá a assistentes de IA (Claude Desktop, Cursor, Antigravity ou seus próprios agentes) controle sobre o Spotify: reprodução, dispositivos, fila, busca, sua biblioteca e playlists.

Destaques

• 32 ferramentas cobrindo reprodução, dispositivos, fila, busca no catálogo, seu histórico de audição e biblioteca, e gerenciamento de playlists, incluindo capa personalizada.
• 6 recursos ambientais (spotify://...) que dão ao assistente contexto como o que está tocando, sua fila e seu perfil de gostos, sem uma chamada de ferramenta.
• Erros amigáveis para agentes. Falhas retornam como JSON estruturado com um error_code e orientação de recuperação (por exemplo, "nenhum dispositivo ativo, chame spotify_get_available_devices") em vez de erros HTTP brutos. Argumentos inválidos são rejeitados antes de chegar ao Spotify.
• Respostas compactas. Os payloads do Spotify são reduzidos aos campos que um assistente realmente precisa, usando menos da janela de contexto.
• Funciona localmente ou via HTTP. Roda via stdio para clientes desktop ou como um servidor HTTP streamable sem estado, e gerencia login OAuth 2.0 PKCE e renovação de token para você.

Visão geral

O servidor encapsula a Spotify Web API como ferramentas e recursos MCP. Um assistente conectado a ele pode lidar com solicitações como "coloque na fila três faixas animadas do Daft Punk", "crie uma playlist com minhas faixas mais tocadas deste mês" ou "mova a reprodução para meu celular".

Ele faz login com sua própria conta do Spotify, usando um aplicativo de desenvolvedor Spotify que você cria (veja Instalação). O controle de reprodução requer Spotify Premium.

Ferramentas

Área	Ferramentas
Reprodução	spotify_play, spotify_pause, spotify_skip_to_next, spotify_skip_to_previous, spotify_seek_to_position, spotify_set_volume, spotify_toggle_shuffle, spotify_set_repeat_mode, spotify_get_playback_state, spotify_get_currently_playing
Dispositivos	spotify_get_available_devices, spotify_transfer_playback
Fila	spotify_get_queue, spotify_add_to_queue
Catálogo	spotify_search_catalog, spotify_get_artist, spotify_get_album
Usuário e biblioteca	spotify_get_user_profile, spotify_get_top_tracks, spotify_get_top_artists, spotify_get_recently_played, spotify_get_saved_tracks
Playlists	spotify_create_playlist, spotify_get_user_playlists, spotify_get_playlist, spotify_get_playlist_items, spotify_add_tracks_to_playlist, spotify_remove_tracks_from_playlist, spotify_reorder_playlist_tracks, spotify_replace_playlist_tracks, spotify_update_playlist_details, spotify_upload_playlist_cover

Recursos: spotify://user/profile, spotify://user/top-tracks, spotify://user/top-artists, spotify://player/current, spotify://player/queue, spotify://playlist/{playlist_id}.

Limitações conhecidas da API do Spotify

Estas são limitações do lado do Spotify, não bugs deste servidor. Cada uma foi confirmada contra a Web API ao vivo ou o changelog do Spotify.

• A visibilidade da playlist não pode ser definida pela API. O Spotify aceita public: false na criação e atualização, mas a playlist permanece pública. Por isso, as ferramentas de playlist não oferecem um parâmetro public. Defina a visibilidade no aplicativo do Spotify. (thread da comunidade)
• O conteúdo das playlists está disponível apenas para playlists que você possui ou colabora. Para outras playlists, spotify_get_playlist retorna metadados com um note explicativo, e spotify_get_playlist_items retorna um erro PLAYLIST_CONTENTS_UNAVAILABLE.
• Metadados de artistas e faixas são reduzidos. O Spotify não retorna mais genres, popularity ou followers em artistas, popularity em faixas, ou label / popularity em álbuns. As faixas mais tocadas de artistas não estão mais disponíveis, então use spotify_search_catalog com artist:"Name" em vez disso.
• A busca retorna no máximo 10 resultados por tipo (padrão 5), e limit + offset não pode exceder 1000.
• A busca de playlists oculta alguns resultados. O Spotify retorna alguns resultados de playlist como null (cerca de 3 em 10 em testes ao vivo). spotify_search_catalog os descarta e informa quantos descartou em playlists_hidden_by_spotify. Se uma página voltar majoritariamente ou totalmente oculta, tente o próximo offset.
• As contagens de faixas de playlists podem ficar desatualizadas. Logo após adicionar faixas, spotify_get_user_playlists pode reportar um tracks_total desatualizado. spotify_get_playlist reporta a contagem atual.

Uso

Após instalar, adicione o servidor ao seu cliente MCP. Para Claude Desktop, edite claude_desktop_config.json:

{
  "mcpServers": {
    "spotify": {
      "command": "/path/to/spotify-mcp-server/.venv/bin/python",
      "args": ["/path/to/spotify-mcp-server/main.py"]
    }
  }
}

Reinicie o cliente e pergunte algo como "O que está tocando agora? Adicione duas faixas semelhantes à minha fila."

Para servir via HTTP streamable em vez disso, para configurações remotas ou com vários clientes:

python main.py --transport http   # serves http://127.0.0.1:8000/mcp

Então aponte seu cliente para http://127.0.0.1:8000/mcp. Use --host e --port para alterar o endereço.

Instalação

Você precisa de Python 3.10 ou mais recente e uma conta do Spotify (Premium para controle de reprodução).

1. Crie um aplicativo de desenvolvedor Spotify

1. Abra o Spotify Developer Dashboard e clique em Create app.
2. Adicione o URI de redirecionamento http://127.0.0.1:8888/callback. Ele deve corresponder exatamente, incluindo a porta e o caminho.
3. Em Which API/SDKs are you planning to use?, selecione Web API, depois salve.
4. Nas Settings do aplicativo, copie o Client ID e o Client Secret.

Novos aplicativos começam no Modo de Desenvolvimento: sua própria conta funciona imediatamente, e outras contas devem ser adicionadas em Settings > User Management.

2. Instale o servidor

git clone https://github.com/AtharvBagade/spotify-mcp-server.git
cd spotify-mcp-server
python3 -m venv .venv && source .venv/bin/activate
pip install -e .

3. Configure as credenciais

cp .env.example .env

Depois preencha .env:

SPOTIFY_CLIENT_ID="your_client_id"
SPOTIFY_CLIENT_SECRET="your_client_secret"
SPOTIFY_REDIRECT_URI="http://127.0.0.1:8888/callback"

# Optional (defaults shown)
SPOTIFY_TOKEN_CACHE_PATH=".spotify_token.json"
MCP_SERVER_NAME="Spotify MCP Server"
MCP_HOST="127.0.0.1"
MCP_PORT=8000
LOG_LEVEL="INFO"

4. Faça login uma vez

python -c "from src.auth import SpotifyAuthManager; from src.config import load_settings; SpotifyAuthManager(load_settings()).get_valid_access_token()"

Uma janela do navegador abre para você entrar no Spotify. O token é armazenado em cache em .spotify_token.json e renovado automaticamente depois disso. Se você pular esta etapa, o mesmo login acontece na primeira chamada de ferramenta. Os logs vão para stderr; defina LOG_LEVEL=DEBUG para incluir tracebacks completos.

Feedback e Contribuições

Relatórios de bugs e solicitações de recursos são bem-vindos em GitHub Issues. Inclua o nome da ferramenta, seus argumentos e o error_code que você recebeu.

Para trabalhar no servidor, instale as dependências de desenvolvimento e execute os testes:

pip install -e ".[dev]"
pytest
ruff check src tests