Amazon Music MCP

Servidor MCP Amazon Music MCP

Toque, pesquise e controle Amazon Music pelo Claude. Peça uma música e ela toca, com um cartão na conversa para os controles de reprodução, a fila e as letras sincronizadas.

A Amazon Music não tem uma API pública de reprodução, então isto não usa uma. É um servidor Model Context Protocol que controla o player web da Amazon Music em uma janela real do Microsoft Edge, posicionada fora da tela, clicando nos mesmos botões que você clicaria.

Não é afiliado à Amazon. Ele automatiza o player web no seu próprio perfil de navegador, conectado como você. O servidor nunca lida com sua senha: login coloca a janela do Edge na tela e você faz login sozinho, incluindo CAPTCHA e 2FA.

Conteúdo

• Instalação
• O que você pode pedir
• O widget do player
• Ferramentas
• Como funciona
• Configuração
• Solução de problemas
• Desenvolvimento
• Licença

Requisitos

Windows, porque o tratamento da janela fora da tela e da barra de tarefas é Win32. Microsoft Edge, porque a Amazon Music transmite sob Widevine DRM e um Chromium embutido não consegue descriptografá-lo. Uma conta Amazon Music, com Unlimited se você quiser que os selos HD e Ultra HD signifiquem algo. Node 20 ou mais recente apenas se você compilar a partir do código-fonte.

Instalação

Claude Desktop

1. Baixe o amazon-music.mcpb do último lançamento.
2. Clique duas vezes nele, ou arraste-o para Claude Desktop → Configurações → Extensões.
3. Reinicie o Claude Desktop.
4. Peça ao Claude para executar login. Uma janela do Edge abre na página de login da Amazon.
5. Faça login lá e depois peça hide_window.

O passo 4 acontece uma vez. A sessão vive em um perfil privado do Edge a partir de então.

Instalar como extensão também é a única maneira de obter um ícone de conector real: o Claude Desktop desenha um avatar de letra para qualquer coisa listada em claude_desktop_config.json e ignora os ícones que um servidor anuncia via MCP.

Outros clientes MCP

É um servidor MCP stdio comum, então qualquer cliente que possa executar um funcionará: Claude Code, Cursor, VS Code, Cline, Continue. Compile a partir do código-fonte primeiro (abaixo) e depois aponte o cliente para dist/index.js:

{
  "mcpServers": {
    "amazon-music": {
      "command": "C:\\Program Files\\nodejs\\node.exe",
      "args": ["C:\\Users\\<you>\\.amazon-music-mcp\\build\\dist\\index.js"],
      "env": {
        "AMZ_PROFILE_DIR": "C:\\Users\\<you>\\.amazon-music-mcp\\profile",
        "AMZ_LOG_FILE": "C:\\Users\\<you>\\.amazon-music-mcp\\logs\\server.log"
      }
    }
  }
}

Todas as 30 ferramentas funcionam em qualquer lugar. O cartão do player precisa de suporte a MCP Apps, que no momento em que este texto foi escrito significa Claude Desktop; em outros lugares você obtém as mesmas informações como texto. O Claude Desktop é o único cliente em que eu realmente o executei.

Compilar a partir do código-fonte

git clone https://github.com/ShadowsDistant/Amazon-Music-MCP.git
cd Amazon-Music-MCP
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\setup.ps1
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\pack-extension.ps1

setup.ps1 copia os fontes para %USERPROFILE%\.amazon-music-mcp\build e executa npm, tsc e o empacotador de widgets lá, então nada pesado vai para o OneDrive. pack-extension.ps1 grava o amazon-music.mcpb instalável ao lado dele.

Dois interruptores opcionais em setup.ps1:

-Install grava a entrada em %APPDATA%\Claude\claude_desktop_config.json, mantendo um backup com carimbo de data/hora. Use-o apenas se quiser o caminho do arquivo de configuração em vez da extensão.

-Autostart coloca um atalho na sua pasta de Inicializar que executa um lançador oculto, para que o Edge fora da tela esteja aquecido antes de você abrir qualquer coisa. Nada toca até você pedir. Remova-o com node "%USERPROFILE%\.amazon-music-mcp\build\scripts\autostart.mjs" --remove.

O que você pode pedir

O Claude escolhe a ferramenta; você apenas conversa.

Você diz	O que acontece
"toque get lucky do daft punk"	Pesquisa e toca a melhor correspondência
"toque o álbum Discovery"	Toca o álbum, não o single
"toque minha playlist de corrida"	Toca uma das suas próprias playlists pelo nome
"coloque Instant Crush na fila"	Adiciona após a faixa atual, sem interrupção
"o que está tocando?"	Título, artista, álbum, qualidade, posição
"quais são as letras?"	Letras completas e a linha que está sendo cantada
"repita esta música" / "repita esta playlist"	Repete uma, ou repete todas
"desligue a reprodução automática"	Impede a Amazon de colocar músicas semelhantes na fila após as suas
"pular" / "pausar" / "mais alto" / "curtir isto"	A coisa óbvia

As solicitações são analisadas antes de serem pesquisadas, então "álbum", "playlist", "estação" e "<title> de <artist>" direcionam o resultado.

O widget do player

Cada captura de tela abaixo é o cartão real mostrando uma faixa real. scripts/shots.mjs o renderiza a partir do que o player está fazendo no momento.

A cor vem da capa do álbum, extraída da arte na página do navegador. A imagem atrás dela é o cenário do artista da Amazon, não a arte da capa ampliada. O tema claro deriva a cor novamente em vez de reutilizá-la, porque um tom que se lê bem em um cartão escuro pode ser invisível em um claro. Qualquer coisa que você precise ler é afastada do fundo até atingir contraste de 4,5:1.

O selo de qualidade carrega os números que a Amazon reporta por trás dele, então "24-bit / 48 kHz" é o que está saindo do navegador agora, não o que a faixa poderia alcançar em hardware melhor.

As letras seguem a música e param de seguir no momento em que você as rola:

Em seguida lê a fila de reprodução da própria Amazon. Clique em uma linha para pular para ela.

Ferramentas

⧉ marca as ferramentas que renderizam o cartão do player.

Ferramenta	Finalidade
status	O navegador está rodando, você está conectado, o que está tocando. Nunca inicia o Edge.
login / hide_window / quit_browser	Mostra a janela para fazer login, esconde-a ou fecha o Edge.
player ⧉	Mostra o cartão do player.
now_playing ⧉	Faixa, arte, cenário, tags, estado, posição, embaralhar/repetir/curtir, letra atual.
lyrics	Letras completas mais o índice da linha que está sendo cantada.
audio_quality	Profundidade de bits e taxa de amostragem da faixa, do dispositivo e da saída.
set_autoplay {enabled?}	Lê ou altera a configuração de Reprodução Automática da Amazon.
play ⧉, pause, play_pause, next ⧉, previous ⧉	Transporte.
set_volume {level}	0 a 100.
shuffle {mode?} / repeat {mode}	ligado/desligado; desligado, todos ou um.
search {query, type?, limit?}	Resultados classificados e tipados com hrefs e tags. Executa na aba de navegação.
play_by_query {query, type?} ⧉	Analisa, pesquisa, toca a melhor correspondência, retorna os segundos colocados.
play_href {href} ⧉	Toca um resultado específico, linha da fila ou playlist.
queue_add {query|href, position?}	Toca em seguida ou adiciona à fila sem interromper.
open_url {url}	Abre qualquer página music.amazon.com e lista o que há nela.
my_playlists / play_playlist {name|href} ⧉	Suas playlists da biblioteca.
like / unlike / add_to_playlist {playlist}	Age sobre a faixa atual.
queue	Próximas faixas.
debug_snapshot {selector?}	Instantâneo de acessibilidade, para reparar seletores.

Como funciona

A janela do Edge é real e está renderizando. Ela fica em -32000,-32000 com seu botão na barra de tarefas removido por um pequeno Win32 via PowerShell. Minimizá-la seria mais fácil, mas o site para de pintar seu shadow DOM no momento em que document.visibilityState fica oculto, e um player que parou de pintar não pode ser clicado.

Tudo roda em um perfil privado em %USERPROFILE%\.amazon-music-mcp\profile com extensões e sincronização desativadas, então seu Edge do dia a dia não é tocado.

Duas abas, cada uma em sua própria janela fora da tela. A aba do player é dona da reprodução e nunca navega enquanto algo está tocando. A aba de navegação assume search, my_playlists e open_url, então um carregamento de página não pode cortar a música. Qualquer terceira aba é fechada no próximo anexo.

O Edge é iniciado destacado e anexado via CDP, então sair do Claude Desktop não interrompe a música.

O runtime vive em %USERPROFILE%\.amazon-music-mcp em vez de %LOCALAPPDATA% por um motivo específico: o Claude Desktop é distribuído como um pacote MSIX, e qualquer coisa que seus processos filhos gravem em AppData é redirecionada para o LocalCache do próprio pacote, onde o lançador de login não consegue encontrá-la.

Velocidade

Uma solicitação "toque X" leva de 1,9 a 2,5 segundos de ponta a ponta, a maior parte com a Amazon pesquisando e armazenando em buffer. Pedir algo que já está tocando responde em cerca de 50 ms. As pesquisas de estado do widget custam de 8 a 17 ms, porque tudo que é caro é aquecido em segundo plano e servido do cache: o cenário do artista, as letras, os números de qualidade, o volume e a configuração de Reprodução Automática chegam um momento após o primeiro desenho do cartão, em vez de segurá-lo.

Parar no final de uma música

A configuração de Reprodução Automática da Amazon só impede que a fila seja estendida. Peça uma única faixa com ela desligada e a Amazon ainda coloca músicas semelhantes na fila, então a reprodução continua direto para música que você nunca pediu.

A correção roda dentro da página. O controle deslizante de progresso reporta apenas segundos inteiros, então o fim exato precisa ser interpolado a partir do momento em que ele avançou pela última vez, e uma ida e volta por pesquisa deixaria um segundo da próxima faixa audível antes que qualquer coisa pudesse reagir. Na página, ele pausa 0,35 s antes, o que deixa a música que você pediu carregada em vez da seguinte. Álbuns, playlists e estações continuam tocando.

Configuração

Variável	Padrão
AMZ_EDGE_EXE	primeiro existente dos caminhos do Edge Program Files (x86) / Program Files
AMZ_PROFILE_DIR	%USERPROFILE%\.amazon-music-mcp\profile
AMZ_CDP_PORT	9333
AMZ_LOG_FILE	não definido, apenas stderr

Limitações conhecidas

As linhas de pesquisa carregam apenas a tag explicit. O payload de pesquisa da Amazon não tem selos de qualidade; os chips Ultra HD, HD e Atmos existem na barra do player, na fila e nas páginas de detalhes, que é de onde vêm essas tags.

As letras e o cenário do artista só existem na Visualização Agora Reproduzindo completa, que precisa ser fechada para que qualquer coisa baseada em linha funcione, já que ela cobre a barra de navegação e a barra do player. O servidor a abre uma vez por faixa em segundo plano, captura ambos, os armazena em cache e a fecha novamente. O destaque sincronizado fica ativo apenas enquanto essa visualização está aberta, o que a ferramenta lyrics organiza; caso contrário, as linhas voltam com activeIndex: -1.

Solução de problemas

As ferramentas expiram ou voltam vazias. Execute status. visibility precisa ser visible. Se for hidden, porque a janela foi minimizada ou a tela foi bloqueada, chame hide_window, que a re-normaliza fora da tela.

not_logged_in. Execute login, faça login e depois hide_window.

Um seletor parou de corresponder, porque a Amazon mudou a página. Chame debug_snapshot, opcionalmente com um seletor CSS, e corrija src/selectors.ts. Toda string específica do site no projeto está nesse único arquivo.

Sem som. Verifique se a janela do Edge não está mutada (login mostra isso) e se o Widevine carregou, em edge://components.

"Não foi possível conectar ao host" no widget. Esse cliente não suporta MCP Apps. Os resultados simples das ferramentas ainda funcionam.

O Edge reapareceu na barra de tarefas. Chame hide_window, que reaplica scripts/taskbar.ps1, ou execute esse script você mesmo com -ProfileDir.

Mais de duas abas. O servidor reduz para a aba do player mais uma aba de navegação em cada anexo. quit_browser seguido por qualquer ferramenta de reprodução dá uma reinicialização limpa.

Logs. %USERPROFILE%\.amazon-music-mcp\logs\server.log, e o próprio log do Claude Desktop %APPDATA%\Claude\logs\mcp-server-amazon-music.log. O servidor nunca grava em stdout.

Removendo-o. node "%USERPROFILE%\.amazon-music-mcp\build\scripts\install.mjs" --remove, e o mesmo para autostart.mjs.

Desenvolvimento

src/index.ts        server bootstrap (stdio), icon + instructions
src/tools.ts        tool schemas, widget resource, error wrapping
src/browser.ts      spawn and attach Edge over CDP, show/hide window, login detection
src/config.ts       paths and the shared Edge command line
src/selectors.ts    every site-specific selector
src/tags.ts         explicit / Ultra HD / HD / Atmos tag parsing
src/accent.ts       album-cover colour extraction, runs in the page, cached per artwork
src/quality.ts      the real bit-depth and sample-rate numbers behind the HD badge
src/singleTrack.ts  the in-page end-of-song stop for single-track requests
src/player.ts       now_playing, transport, volume, shuffle/repeat, like, queue
src/search.ts       query parsing and ranking, play_by_query, play_href, queue_add
src/library.ts      playlists, add_to_playlist
ui/player.html+ts   the MCP App widget, bundled by scripts/build-ui.mjs

Duas coisas sobre o site valem a pena saber antes de mudar qualquer coisa. A Amazon Music é construída com componentes web Stencil com shadow roots abertos, então seletores CSS comuns os atravessam no Playwright e nada de inteligente é necessário. E as linhas de resultado existem como esqueletos vazios antes de hidratarem, que é o motivo pelo qual itemReady insiste em [primary-text]; corresponda à tag pura e você analisará uma página de espaços em branco.

Testar sem um cliente

& "C:\Program Files\nodejs\node.exe" "$HOME\.amazon-music-mcp\build\scripts\smoke.mjs" --play

Gera o servidor via stdio como um cliente faria, lista as ferramentas e executa status, search e debug_snapshot. Com --play, e se você estiver conectado, ele também executa play_by_query, now_playing e pause. Adicione --quit para fechar o Edge no final.

Qualquer ferramenta, diretamente, de um shell estilo bash para que o JSON sobreviva às aspas:

node "$HOME/.amazon-music-mcp/build/scripts/call.mjs" play_by_query '{"query":"get lucky"}' now_playing

node scripts/serve-ui.mjs serve o widget em http://localhost:8765 sem nenhum host por trás dele. ?demo o preenche com uma faixa de exemplo, ?demo&lyrics e ?demo&queue abrem os painéis, ?skeleton mostra o estado de carregamento, ?accent=r,g,b verifica a correção de contraste em relação a uma capa estranha, e ?demo&poll re-renderiza no intervalo de polling da mesma forma que um host o aciona. Qualquer coisa que seja reconstruída ou re-animada sob ?demo&poll é um flicker, então observe isso com um MutationObserver em vez de a olho nu.

Cada ferramenta registra sua duração no stderr. play_by_query detalha isso por fase, e as linhas waitForTrack e single-track dizem o que o player realmente fez. Quando a reprodução se comportar mal, leia essas primeiro.

scripts/shots.mjs [outDir] regenera as capturas de tela acima a partir do estado ao vivo do player. Reproduza algo primeiro.

Licença

GNU General Public License v3.0 ou posterior.

Este programa é software livre: você pode redistribuí-lo e/ou modificá-lo sob os termos da GNU General Public License conforme publicada pela Free Software Foundation, seja a versão 3 da Licença, ou (a seu critério) qualquer versão posterior. Ele é distribuído na esperança de que seja útil, mas SEM NENHUMA GARANTIA; sem sequer a garantia implícita de COMERCIABILIDADE ou ADEQUAÇÃO A UM DETERMINADO FIM. Consulte a licença para obter detalhes.