ESP32-C3 MCP Musikserver

Das Stammverzeichnis dieses Projekts ist ein MCP-Server, der es OpenClaw, Claude Desktop oder anderen MCP-Agenten ermöglicht, einen ESP32-C3-Audioclient über MQTT zur Musikwiedergabe zu steuern.

Die Anweisungen zur ESP32-C3-Firmware finden Sie unter esp32-c3-client/README.md.

Funktionen

• Senden von Steuerbefehlen wie Abspielen, Pausieren, Stoppen, Lautstärke und Nächster Titel an den ESP32-C3 via MQTT

• Einlesen der Songliste aus einem HTTP-Musikverzeichnis

• Unterstützung für die Suche und Wiedergabe nach Songnamen

• Unterstützung für die sequentielle Wiedergabe der gesamten Musikliste

• Unterstützung für das Schreiben von Wiedergabelisten in ein MQTT-retained-Topic, damit der ESP32-C3 diese selbstständig nacheinander abspielen kann

• Unterstützung für das Löschen der gespeicherten Wi-Fi-Konfiguration des ESP32-C3, um erneut in den mobilen Konfigurationsmodus zu gelangen

Voraussetzungen

• Node.js 18 oder höher

• Ein zugänglicher MQTT-Broker

• ESP32-C3-Client muss geflasht und mit demselben MQTT-Broker verbunden sein

• Ein HTTP-Musikverzeichnis, z. B. ein von nginx bereitgestelltes Verzeichnis mit MP3-Dateien

Installation

npm install

Kopieren Sie die Umgebungsvariablen-Vorlage:

copy .env.example .env

Unter Windows PowerShell können Sie auch Folgendes verwenden:

Copy-Item .env.example .env

Passen Sie anschließend .env an Ihre Gegebenheiten an.

Umgebungsvariablen

MQTT_BROKER=mqtt://esp32:esp32mqtt2026@localhost:1883
MQTT_TOPIC=esp32-c3/music/play
MQTT_PLAYLIST_TOPIC=esp32-c3/music/playlist/active
MUSIC_LIBRARY_URL=http://47.102.147.204:8080/mp3/
FETCH_TIMEOUT_MS=8000
MAX_PLAYLIST_FETCHES=3
MAX_PLAYLIST_ITEMS=50

Erläuterungen:

• MQTT_BROKER: Verbindungsadresse des MQTT-Brokers, unterstützt URLs mit Benutzername und Passwort

• MQTT_TOPIC: Topic, unter dem der ESP32-C3 Steuerbefehle empfängt

• MQTT_PLAYLIST_TOPIC: Präfix für das retained Cache-Topic der Wiedergabeliste

• MUSIC_LIBRARY_URL: URL des HTTP-Musikverzeichnisses, kann ohne abschließenden / angegeben werden

• FETCH_TIMEOUT_MS: Timeout für das Abrufen des Musikverzeichnisses oder der Wiedergabelistendateien

• MAX_PLAYLIST_FETCHES: Maximale Anzahl der zu analysierenden Wiedergabelistendateien

• MAX_PLAYLIST_ITEMS: Maximale Anzahl der Songs, die bei sequentieller Wiedergabe zwischengespeichert werden

MCP-Konfigurationsbeispiel

In Agenten, die MCP-stdio-Server unterstützen, konfigurieren Sie den Befehl wie folgt:

{
  "mcpServers": {
    "esp32-c3-music": {
      "command": "node",
      "args": ["D:\\ESP32-C3-MCP\\index.js"],
      "cwd": "D:\\ESP32-C3-MCP"
    }
  }
}

Wenn der Agent Umgebungsvariablen unterstützt, können Sie die Variablen aus .env auch direkt in die MCP-Server-Konfiguration einfügen.

Verfügbare Werkzeuge

list_music_library

Scannt die MUSIC_LIBRARY_URL und gibt die gefundenen Songnamen und URLs zurück.

play_music

Spielt einen bestimmten Song ab. Sie können Folgendes übergeben:

• url: Spielt diese URL direkt ab

• song_name: Sucht in der Musikbibliothek nach dem Namen und spielt ihn ab

Wenn sowohl url als auch song_name übergeben werden, hat url Vorrang.

play_song_from_library

Sucht und spielt nur anhand des song_name aus der Musikbibliothek.

play_playlist

Spielt die Musikliste sequentiell ab.

Dabei wird die Liste zuerst in ein MQTT-retained-Topic geschrieben:

esp32-c3/music/playlist/active/meta
esp32-c3/music/playlist/active/item/0
esp32-c3/music/playlist/active/item/1

Anschließend wird an MQTT_TOPIC gesendet:

{"action":"play_playlist","start_index":0}

Sobald der ESP32-C3 dies empfängt, beginnt er mit der Wiedergabe ab der lokal zwischengespeicherten Liste und spielt nach Beendigung des aktuellen Songs automatisch den nächsten ab. Auf diese Weise muss der MCP-Server nicht ständig online sein.

Parameter:

• start_index: Ab welchem Song begonnen werden soll, Standard 0

• max_songs: Maximale Anzahl der zu cachenden und abzuspielenden Songs, Standard MAX_PLAYLIST_ITEMS

next_music

Nächster Titel oder Liedwechsel.

• Übergabe von url oder song_name: Springt direkt zum angegebenen Song und behält die ursprüngliche Logik für die Einzelwiedergabe bei

• Keine Parameter: Sendet playlist_next, damit der ESP32-C3 im Wiedergabelistenmodus zum nächsten Titel springt

pause_music

Pausiert die Wiedergabe. Der ESP32-C3 stoppt die aktuelle Wiedergabe, behält aber die letzte URL bei.

stop_music

Stoppt die Wiedergabe und löscht die letzte URL. Der Wiedergabelistenmodus wird ebenfalls beendet.

set_volume

Stellt die Lautstärke ein, Bereich 0-100.

reset_wifi

Sendet:

{"action":"reset_wifi"}

Nach Erhalt löscht der ESP32-C3 die gespeicherte Wi-Fi-Konfiguration und startet neu. Nach dem Neustart wird der mobile Konfigurations-Hotspot aktiviert.

Hinweis: Dieses Werkzeug erfordert, dass der ESP32-C3 aktuell online ist und mit MQTT verbunden ist. Wenn das Gerät bereits offline ist, kann es diese MQTT-Nachricht nicht empfangen und muss warten, bis die Firmware nach einem Verbindungsfehler automatisch den Konfigurations-Hotspot öffnet.

MQTT-Nachrichtenkonventionen

Das Standard-Steuerungs-Topic ist:

esp32-c3/music/play

Übliche Steuernachrichten:

{"action":"play","url":"http://example.com/song.mp3"}
{"action":"next","url":"http://example.com/next.mp3"}
{"action":"pause"}
{"action":"stop"}
{"action":"set_volume","volume":65}
{"action":"play_playlist","start_index":0}
{"action":"playlist_next"}
{"action":"reset_wifi"}

Das Standard-Präfix für das Wiedergabelisten-Topic ist:

esp32-c3/music/playlist/active

Der MCP-Server veröffentlicht retained Nachrichten, die der ESP32-C3 abonniert:

esp32-c3/music/playlist/active/#

Lokale Überprüfung

Überprüfung der Node.js-Syntax:

node --check index.js

Die aktuelle package.json enthält noch keine automatisierten Testskripte.