Music Assistant per Docker mit Home Assistant verbinden

Veröffentlicht am 12. August 2026 · Geschätzte Lesezeit: 5 Minuten

Music Assistant bündelt lokale Musik und unterstützte Streamingdienste und verteilt sie an Lautsprecher im Heimnetz. Der Server läuft separat in Docker; die offizielle Home-Assistant-Integration macht die Player für Bedienung und Automationen verfügbar. Plane für Installation und ersten Test etwa 25 bis 40 Minuten ein.

Voraussetzungen

• Ein Linux-Server mit Docker und Docker Compose
• Home Assistant und die Lautsprecher im selben lokalen Netzwerk
• Mindestens 2 GB Arbeitsspeicher auf dem Gerät
• Optional ein lokaler oder auf dem Host eingebundener Musikordner

1. Ordner vorbereiten

Führe den Befehl auf dem Docker-Server aus. Er erstellt einen dauerhaften Datenordner und wechselt in das Projektverzeichnis.

mkdir -p ~/docker/music-assistant/data && cd ~/docker/music-assistant

Wenn du eigene Musik verwendest, muss sie auf dem Docker-Host bereits erreichbar sein. In dieser Anleitung lautet der Beispielpfad /mnt/musik. Ersetze ihn später durch deinen tatsächlichen Pfad.

2. Compose-Datei anlegen

Lege im Ordner ~/docker/music-assistant die Datei compose.yaml an. Ersetze <musik-pfad> durch den vollständigen Ordner deiner Musiksammlung, zum Beispiel /mnt/musik. Hast du keine lokalen Musikdateien, entferne die zweite Volume-Zeile.

services:
  music-assistant:
    image: ghcr.io/music-assistant/server:latest
    container_name: music-assistant
    restart: unless-stopped
    network_mode: host
    volumes:
      - ./data:/data
      - <musik-pfad>:/media:ro
    environment:
      LOG_LEVEL: info

Der Zusatz :ro bindet die Musik nur lesbar ein. Music Assistant kann dann keine Originaldateien verändern oder löschen.

Host-Netzwerk ist erforderlich

Music Assistant benötigt für mDNS, UPnP und die direkte Kommunikation mit AirPlay-, Chromecast-, DLNA- oder Sonos-Geräten Zugriff auf das Host-Netzwerk. Dadurch gibt es keine zusätzliche Netzwerkisolation durch Docker. Stelle die Weboberfläche nicht per Router-Portfreigabe ins Internet.

3. Container starten

Starte Music Assistant im Projektordner.

docker compose up -d

Prüfe den Status.

docker compose ps

Zeige anschließend die letzten Protokollzeilen an. Dort sollte eine Meldung mit der Webadresse und Port 8095 erscheinen.

docker compose logs --tail=100 music-assistant

4. Ersteinrichtung abschließen

Öffne http://<server-ip>:8095 im Browser. Ersetze <server-ip> durch die feste IP-Adresse des Docker-Servers, beispielsweise 192.168.178.20.

Lege beim ersten Start ein Administratorkonto mit einem langen, einzigartigen Passwort an. Dieses Konto wird später auch für die Verbindung zu Home Assistant benötigt.

Nicht öffentlich freigeben

Die Weboberfläche und der Stream-Port 8097 gehören ins Heimnetz. Nutze für entfernten Zugriff ein VPN. Eine einfache Portfreigabe im Router würde Anmeldung und Audiostream unnötig angreifbar machen.

5. Musikquelle hinzufügen

Öffne in Music Assistant Settings → Music Sources → Add Music Source.

Für eigene Dateien wählst du Filesystem (local disk) und trägst /media ein. Dieser Containerpfad entspricht dem im Compose-Block eingetragenen <musik-pfad> auf dem Host.

Für einen Streamingdienst wählst du dessen Anbieter und folgst dem jeweiligen Anmeldedialog. Speichere keine Zugangsdaten in der Compose-Datei. Beachte außerdem die Bedingungen deines Streaminganbieters.

6. Lautsprecher hinzufügen

Gehe zu Settings → Player Providers → Add a Player Provider und wähle den passenden Gerätetyp, beispielsweise Sonos, Google Cast oder DLNA. Aktiviere danach den erkannten Lautsprecher.

Wird kein Gerät gefunden, prüfe zuerst:

• Music Assistant und Lautsprecher befinden sich im selben Layer-2-Netz beziehungsweise VLAN.
• WLAN-Client-Isolation ist im Router ausgeschaltet.
• Die lokale Firewall blockiert keine Multicast- oder eingehenden Verbindungen.
• Der Container verwendet wirklich network_mode: host.

7. Home-Assistant-Integration einrichten

Öffne in Home Assistant Einstellungen → Geräte & Dienste. Normalerweise wird Music Assistant automatisch gefunden. Klicke dann auf Konfigurieren.

Falls kein Fund erscheint, wähle Integration hinzufügen, suche nach Music Assistant und gib folgende Adresse ein:

http://<server-ip>:8095

Ersetze <server-ip> durch die IP des Docker-Servers. Melde dich mit dem in Music Assistant erstellten Administratorkonto an. Laut offizieller Dokumentation braucht die Integration dieses Konto für alle Funktionen und einige Aktionen funktionieren mit einem normalen Benutzer nicht.

8. Wiedergabe testen

Öffne in Music Assistant einen Titel oder Radiosender, wähle den eingerichteten Player und starte die Wiedergabe. Prüfe anschließend in Home Assistant unter Einstellungen → Geräte & Dienste → Music Assistant → Entitäten, ob eine passende media_player-Entität vorhanden ist.

Zum Test einer vorhandenen Entität kannst du in Home Assistant unter Entwicklerwerkzeuge → Aktionen die Aktion media_player.media_play_pause auswählen und als Ziel den Music-Assistant-Player setzen.

9. Aktualisieren und zurückrollen

Erstelle vor einem Update zuerst ein Backup des Datenordners.

cd ~/docker/music-assistant && docker compose stop

tar -czf music-assistant-backup-$(date +%Y%m%d).tar.gz data compose.yaml

Starte danach wieder und aktualisiere nur, wenn das Backup außerhalb des Servers gesichert ist.

docker compose pull

docker compose up -d

Falls die neue Version Probleme verursacht, trage im Compose-Block statt latest den zuvor verwendeten Release-Tag ein, stelle bei Bedarf den Ordner data aus dem Backup wieder her und starte den Stack erneut.

10. Sicher entfernen

Entferne zuerst in Home Assistant die Integration Music Assistant. Stoppe dann den Container, ohne den Datenordner zu löschen.

cd ~/docker/music-assistant && docker compose down

Der Ordner data bleibt erhalten. Wenn du später erneut startest, stehen Benutzer und Einstellungen wieder zur Verfügung. Lösche ihn erst, wenn Music Assistant endgültig entfernt werden soll und ein Backup vorhanden ist.

11. Typische Fehler

• Webseite auf Port 8095 nicht erreichbar: Prüfe Protokoll, Host-Firewall und ob bereits ein anderer Dienst Port 8095 nutzt.
• Player wird nicht gefunden: Host-Netzwerk fehlt, Geräte sind in getrennten VLANs oder WLAN-Isolation blockiert Multicast.
• Lokale Titel fehlen: Der Hostpfad ist falsch oder für Docker nicht lesbar. Im Container muss die Sammlung unter /media erscheinen.
• Home Assistant meldet Berechtigungsfehler: Verbinde die Integration erneut mit einem Music-Assistant-Administratorkonto.
• Titel startet, aber kein Ton kommt: Der Player muss den Stream-Port 8097 auf dem Docker-Server erreichen können.

12. Quellen und Videos

• Music Assistant: offizielle Docker-Installation
• Music Assistant: Home-Assistant-Integration
• Home Assistant: Music Assistant
• Deutsches Video: Music Assistant Schritt für Schritt
• Deutsches Grundlagenvideo zu Music Assistant

Fertig

Music Assistant verwaltet nun mindestens eine Musikquelle und einen Player, Home Assistant zeigt den Player als Entität an. Eine erfolgreiche Funktionsprüfung ist ein gestarteter Titel, dessen Wiedergabestatus gleichzeitig in Music Assistant und Home Assistant sichtbar ist.