ESP32-C3 MCP Music Server
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 installKopieren Sie die Umgebungsvariablen-Vorlage:
copy .env.example .envUnter Windows PowerShell können Sie auch Folgendes verwenden:
Copy-Item .env.example .envPassen 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=50Erläuterungen:
MQTT_BROKER: Verbindungsadresse des MQTT-Brokers, unterstützt URLs mit Benutzername und PasswortMQTT_TOPIC: Topic, unter dem der ESP32-C3 Steuerbefehle empfängtMQTT_PLAYLIST_TOPIC: Präfix für das retained Cache-Topic der WiedergabelisteMUSIC_LIBRARY_URL: URL des HTTP-Musikverzeichnisses, kann ohne abschließenden/angegeben werdenFETCH_TIMEOUT_MS: Timeout für das Abrufen des Musikverzeichnisses oder der WiedergabelistendateienMAX_PLAYLIST_FETCHES: Maximale Anzahl der zu analysierenden WiedergabelistendateienMAX_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 absong_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/1Anschließ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, Standard0max_songs: Maximale Anzahl der zu cachenden und abzuspielenden Songs, StandardMAX_PLAYLIST_ITEMS
next_music
Nächster Titel oder Liedwechsel.
Übergabe von
urlodersong_name: Springt direkt zum angegebenen Song und behält die ursprüngliche Logik für die Einzelwiedergabe beiKeine 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/activeDer 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.jsDie aktuelle package.json enthält noch keine automatisierten Testskripte.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Related MCP Connectors
AI music and podcast platform for autonomous agents. SoundCloud for AI bots.
Audio for your agent: transcribe, speak, translate, summarise, plus sound effects and music.
Give your AI agent the power to cast to your home TV and control an interactive canvas. By ArdaBot.
Autonomous music production for AI agents with MIDI generation, QC and provenance.