Amazon Music MCP

Servidor MCP de Amazon Music

Reproduce, busca y controla Amazon Music desde Claude. Pide una canción y la reproduce, con una tarjeta en la conversación para los controles de transporte, la cola y las letras sincronizadas.

Amazon Music no tiene una API pública de reproducción, así que esto no usa una. Es un servidor de Model Context Protocol que controla el reproductor web de Amazon Music en una ventana real de Microsoft Edge, colocada fuera de pantalla, haciendo clic en los mismos botones que harías tú.

No está afiliado a Amazon. Automatiza el reproductor web en tu propio perfil de navegador, con tu sesión iniciada. El servidor nunca maneja tu contraseña: login pone la ventana de Edge en pantalla y tú inicias sesión tú mismo, incluidos CAPTCHA y 2FA.

Contenido

• Instalación
• Lo que puedes pedir
• El widget del reproductor
• Herramientas
• Cómo funciona
• Configuración
• Solución de problemas
• Desarrollo
• Licencia

Requisitos

Windows, porque la ventana fuera de pantalla y el manejo de la barra de tareas son Win32. Microsoft Edge, porque Amazon Music transmite bajo Widevine DRM y un Chromium incluido no puede descifrarlo. Una cuenta de Amazon Music, con Unlimited si quieres que las insignias de HD y Ultra HD digan algo. Node 20 o más reciente solo si compilas desde el código fuente.

Instalación

Claude Desktop

1. Descarga amazon-music.mcpb desde la última versión.
2. Haz doble clic en él, o arrástralo a Claude Desktop → Configuración → Extensiones.
3. Reinicia Claude Desktop.
4. Pide a Claude que ejecute login. Se abre una ventana de Edge en la página de inicio de sesión de Amazon.
5. Inicia sesión allí, luego pide hide_window.

El paso 4 ocurre una vez. La sesión vive en un perfil privado de Edge a partir de entonces.

Instalar como extensión es también la única forma de obtener un icono de conector real: Claude Desktop dibuja un avatar con una letra para cualquier cosa listada en claude_desktop_config.json e ignora los iconos que un servidor anuncia a través de MCP.

Otros clientes MCP

Es un servidor MCP stdio ordinario, así que cualquier cliente que pueda ejecutar uno funcionará: Claude Code, Cursor, VS Code, Cline, Continue. Compila desde el código fuente primero (abajo), luego apunta el cliente a 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"
      }
    }
  }
}

Las 30 herramientas funcionan en cualquier lugar. La tarjeta del reproductor necesita soporte de MCP Apps, que al momento de escribir esto significa Claude Desktop; en otros lugares obtienes la misma información como texto. Claude Desktop es el único cliente en el que realmente lo he ejecutado.

Compilar desde el código fuente

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 las fuentes a %USERPROFILE%\.amazon-music-mcp\build y ejecuta npm, tsc y el empaquetador de widgets allí, para que nada pesado termine en OneDrive. pack-extension.ps1 escribe el amazon-music.mcpb instalable junto a él.

Dos interruptores opcionales en setup.ps1:

-Install escribe la entrada en %APPDATA%\Claude\claude_desktop_config.json, manteniendo una copia de seguridad con marca de tiempo. Úsalo solo si quieres la ruta del archivo de configuración en lugar de la extensión.

-Autostart coloca un acceso directo en tu carpeta de Inicio que ejecuta un lanzador oculto, para que Edge fuera de pantalla esté caliente antes de que abras cualquier cosa. Nada se reproduce hasta que lo pides. Elimínalo con node "%USERPROFILE%\.amazon-music-mcp\build\scripts\autostart.mjs" --remove.

Lo que puedes pedir

Claude elige la herramienta; tú solo hablas.

Tú dices	Qué sucede
"reproduce get lucky de daft punk"	Busca y reproduce la mejor coincidencia
"reproduce el álbum Discovery"	Reproduce el álbum, no el sencillo
"reproduce mi lista de reproducción de correr"	Reproduce una de tus propias listas por nombre
"pon en cola Instant Crush"	La añade después de la pista actual, sin interrupción
"¿qué está sonando?"	Título, artista, álbum, calidad, posición
"¿cuáles son las letras?"	Letras completas y la línea que se está cantando
"repite esta canción" / "repite esta lista"	Repite una, o repite todas
"apaga la reproducción automática"	Detiene que Amazon ponga en cola canciones similares después de las tuyas
"saltar" / "pausar" / "más alto" / "me gusta esto"	Lo obvio

Las solicitudes se analizan antes de buscarse, así que "álbum", "lista de reproducción", "estación" y "<title> de <artist>" dirigen el resultado.

El widget del reproductor

Cada captura de pantalla abajo es la tarjeta real mostrando una pista real. scripts/shots.mjs la renderiza desde lo que el reproductor está haciendo en ese momento.

El color proviene de la portada del álbum, extraído del arte en la página del navegador. La imagen detrás es el telón de fondo del artista de Amazon, no la portada ampliada. El tema claro deriva el color de nuevo en lugar de reutilizarlo, porque un tinte que se lee bien en una tarjeta oscura puede ser invisible en una pálida. Cualquier cosa que tengas que leer se aleja del fondo hasta que supera el contraste 4.5:1.

La insignia de calidad lleva los números que Amazon reporta detrás, así que "24-bit / 48 kHz" es lo que está saliendo del navegador ahora, no lo que la pista podría manejar en mejor hardware.

Las letras siguen la canción y dejan de seguirla en el momento en que las desplazas tú mismo:

A continuación lee la cola de reproducción propia de Amazon. Haz clic en una fila para saltar a ella.

Herramientas

⧉ marca las herramientas que renderizan la tarjeta del reproductor.

Herramienta	Propósito
status	¿Está el navegador ejecutándose, has iniciado sesión, qué está sonando? Nunca lanza Edge.
login / hide_window / quit_browser	Muestra la ventana para iniciar sesión, la guarda o cierra Edge.
player ⧉	Muestra la tarjeta del reproductor.
now_playing ⧉	Pista, arte, telón de fondo, etiquetas, estado, posición, aleatorio/repetir/me gusta, letra actual.
lyrics	Letras completas más el índice de la línea que se está cantando.
audio_quality	Profundidad de bits y frecuencia de muestreo para la pista, el dispositivo y la salida.
set_autoplay {enabled?}	Lee o cambia la configuración de Reproducción automática de Amazon.
play ⧉, pause, play_pause, next ⧉, previous ⧉	Transporte.
set_volume {level}	0 a 100.
shuffle {mode?} / repeat {mode}	activado/desactivado; desactivado, todo o uno.
search {query, type?, limit?}	Resultados clasificados y tipados con hrefs y etiquetas. Se ejecuta en la pestaña de navegación.
play_by_query {query, type?} ⧉	Analiza, busca, reproduce la mejor coincidencia, devuelve los subcampeones.
play_href {href} ⧉	Reproduce un resultado específico, fila de cola o lista de reproducción.
queue_add {query|href, position?}	Reproduce a continuación o añade a la cola sin interrumpir.
open_url {url}	Abre cualquier página de music.amazon.com y lista lo que hay en ella.
my_playlists / play_playlist {name|href} ⧉	Tus listas de reproducción de la biblioteca.
like / unlike / add_to_playlist {playlist}	Actúa sobre la pista actual.
queue	Pistas próximas.
debug_snapshot {selector?}	Instantánea de accesibilidad, para reparar selectores.

Cómo funciona

La ventana de Edge es real y está renderizando. Se sitúa en -32000,-32000 con su botón de barra de tareas eliminado por un pequeño Win32 a través de PowerShell. Minimizarla sería más fácil, pero el sitio deja de pintar su shadow DOM en el momento en que document.visibilityState se oculta, y un reproductor que ha dejado de pintar no se puede hacer clic.

Todo se ejecuta en un perfil privado en %USERPROFILE%\.amazon-music-mcp\profile con extensiones y sincronización desactivadas, así que tu Edge cotidiano no se toca.

Dos pestañas, cada una en su propia ventana fuera de pantalla. La pestaña del reproductor posee la reproducción y nunca navega mientras algo está sonando. La pestaña de navegación toma search, my_playlists y open_url, así que una carga de página no puede cortar la música. Cualquier tercera pestaña se cierra en la siguiente conexión.

Edge se inicia separado y se conecta a través de CDP, así que salir de Claude Desktop no detiene la música.

El tiempo de ejecución vive en %USERPROFILE%\.amazon-music-mcp en lugar de %LOCALAPPDATA% por una razón específica: Claude Desktop se distribuye como un paquete MSIX, y cualquier cosa que sus procesos hijos escriban bajo AppData se redirige al LocalCache del propio paquete, donde el lanzador de inicio de sesión no puede encontrarlo.

Velocidad

Una solicitud de "reproduce X" toma de 1.9 a 2.5 segundos de extremo a extremo, la mayor parte en la búsqueda y el almacenamiento en búfer de Amazon. Pedir algo que ya está sonando responde en unos 50 ms. Las consultas de estado del widget cuestan de 8 a 17 ms, porque todo lo costoso se calienta en segundo plano y se sirve desde caché: el telón de fondo del artista, las letras, los números de calidad, el volumen y la configuración de Reproducción automática llegan un momento después de que la tarjeta se pinta por primera vez en lugar de retenerla.

Detenerse al final de una canción

La configuración de Reproducción automática de Amazon solo detiene que la cola se extienda. Pide una sola pista con ella desactivada y Amazon aún pone en cola canciones similares, así que la reproducción continúa directamente hacia música que nunca pediste.

La solución se ejecuta dentro de la página. El control deslizante de progreso reporta solo segundos completos, así que el final exacto tiene que interpolarse desde el momento en que avanzó por última vez, y un viaje de ida y vuelta por consulta dejaría un segundo de la siguiente pista audible antes de que algo pudiera reaccionar. En la página pausa 0.35 s antes, lo que deja la canción que pediste cargada en lugar de la siguiente. Los álbumes, listas de reproducción y estaciones siguen reproduciéndose.

Configuración

Variable	Predeterminado
AMZ_EDGE_EXE	primera existente de las rutas de Edge Program Files (x86) / Program Files
AMZ_PROFILE_DIR	%USERPROFILE%\.amazon-music-mcp\profile
AMZ_CDP_PORT	9333
AMZ_LOG_FILE	sin establecer, solo stderr

Límites conocidos

Las filas de búsqueda llevan solo la etiqueta explicit. El payload de búsqueda de Amazon no tiene insignias de calidad en absoluto; los chips de Ultra HD, HD y Atmos existen en la barra del reproductor, en la cola y en las páginas de detalle, que es de donde provienen esas etiquetas.

Las letras y el telón de fondo del artista solo existen en la Vista de Reproducción Actual completa, que tiene que cerrarse para que funcione cualquier cosa basada en filas, ya que cubre la barra de navegación y la barra del reproductor. El servidor la abre una vez por pista en segundo plano, toma ambas cosas, las almacena en caché y la cierra de nuevo. El resaltado sincronizado está activo solo mientras esa vista está abierta, lo que la herramienta lyrics organiza; de lo contrario, las líneas vuelven con activeIndex: -1.

Solución de problemas

Las herramientas agotan el tiempo o vuelven vacías. Ejecuta status. visibility tiene que ser visible. Si es hidden, porque la ventana se minimizó o la pantalla se bloqueó, llama a hide_window, que la re-normaliza fuera de pantalla.

not_logged_in. Ejecuta login, inicia sesión, luego hide_window.

Un selector dejó de coincidir, porque Amazon cambió la página. Llama a debug_snapshot, opcionalmente con un selector CSS, y arregla src/selectors.ts. Cada cadena específica del sitio en el proyecto está en ese único archivo.

Sin sonido. Verifica que la ventana de Edge no esté silenciada (login lo muestra) y que Widevine se cargó, bajo edge://components.

"No se pudo conectar al host" en el widget. Ese cliente no soporta MCP Apps. Los resultados de herramientas simples aún funcionan.

Edge reapareció en la barra de tareas. Llama a hide_window, que re-aplica scripts/taskbar.ps1, o ejecuta ese script tú mismo con -ProfileDir.

Más de dos pestañas. El servidor recorta a la pestaña del reproductor más una pestaña de navegación en cada conexión. quit_browser seguido de cualquier herramienta de reproducción da un reinicio limpio.

Registros. %USERPROFILE%\.amazon-music-mcp\logs\server.log, y los propios de Claude Desktop %APPDATA%\Claude\logs\mcp-server-amazon-music.log. El servidor nunca escribe en stdout.

Eliminarlo. node "%USERPROFILE%\.amazon-music-mcp\build\scripts\install.mjs" --remove, y lo mismo para autostart.mjs.

Desarrollo

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

Dos cosas sobre el sitio valen la pena saber antes de cambiar cualquier cosa. Amazon Music está construido con componentes web de Stencil con raíces shadow abiertas, así que los selectores CSS ordinarios las atraviesan en Playwright y no se necesita nada ingenioso. Y las filas de resultados existen como esqueletos vacíos antes de hidratarse, que es por lo que itemReady insiste en [primary-text]; coincide con la etiqueta desnuda y analizarás una página de espacios en blanco.

Pruebas sin un cliente

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

Genera el servidor a través de stdio como lo haría un cliente, lista las herramientas y ejecuta status, search y debug_snapshot. Con --play, y si has iniciado sesión, también ejecuta play_by_query, now_playing y pause. Añade --quit para cerrar Edge al final.

Cualquier herramienta, directamente, desde un shell de estilo bash para que el JSON sobreviva a las comillas:

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

node scripts/serve-ui.mjs sirve el widget en http://localhost:8765 sin ningún host detrás. ?demo lo rellena con una pista de muestra, ?demo&lyrics y ?demo&queue abren los paneles, ?skeleton muestra el estado de carga, ?accent=r,g,b comprueba la corrección de contraste contra una portada complicada, y ?demo&poll vuelve a renderizar en el intervalo de sondeo de la misma manera que un host lo impulsa. Cualquier cosa que se reconstruya o se re-anime bajo ?demo&poll es un parpadeo, así que vigílalo con un MutationObserver en lugar de a simple vista.

Cada herramienta registra su duración en stderr. play_by_query desglosa eso por fase, y las líneas waitForTrack y single-track indican lo que el reproductor realmente hizo. Cuando la reproducción se comporte mal, lee esas primero.

scripts/shots.mjs [outDir] regenera las capturas de pantalla anteriores desde el estado en vivo del reproductor. Reproduce algo primero.

Licencia

GNU General Public License v3.0 o posterior.

Este programa es software libre: puedes redistribuirlo y modificarlo bajo los términos de la GNU General Public License publicada por la Free Software Foundation, ya sea la versión 3 de la Licencia, o (a tu elección) cualquier versión posterior. Se distribuye con la esperanza de que sea útil, pero SIN NINGUNA GARANTÍA; sin siquiera la garantía implícita de COMERCIABILIDAD o IDONEIDAD PARA UN PROPÓSITO PARTICULAR. Consulta la licencia para más detalles.