ESP32-C3 MCP Music Server

The root directory of this project is an MCP server designed to allow OpenClaw, Claude Desktop, or other MCP agents to control an ESP32-C3 audio client via MQTT for music playback.

ESP32-C3 firmware instructions are in esp32-c3-client/README.md.

Features

• Send control commands such as play, pause, stop, volume, and next track to the ESP32-C3 via MQTT

• Read song lists from an HTTP music directory

• Support searching and playing by song name

• Support sequential playback of the entire music list

• Support writing playlists to an MQTT retained topic, allowing the ESP32-C3 to play them sequentially on its own

• Support clearing saved Wi-Fi configurations on the ESP32-C3 to re-enter mobile provisioning mode

Requirements

• Node.js 18 or higher

• An accessible MQTT broker

• ESP32-C3 client flashed and connected to the same MQTT broker

• An HTTP music directory, such as an MP3 file directory exposed by nginx

Installation

npm install

Copy the environment variable template:

copy .env.example .env

Windows PowerShell can also be used:

Copy-Item .env.example .env

Then modify .env according to your actual situation.

Environment Variables

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

Notes:

• MQTT_BROKER: MQTT broker connection address, supports URLs with username and password

• MQTT_TOPIC: Topic for the ESP32-C3 to receive control commands

• MQTT_PLAYLIST_TOPIC: Prefix for the playlist retained cache topic

• MUSIC_LIBRARY_URL: HTTP music directory address, trailing / is optional

• FETCH_TIMEOUT_MS: Timeout for fetching the music directory or playlist files

• MAX_PLAYLIST_FETCHES: Maximum number of playlist files to parse

• MAX_PLAYLIST_ITEMS: Maximum number of songs to cache during sequential playback

MCP Configuration Example

In an agent that supports MCP stdio server, configure the command as follows:

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

If the agent supports environment variables, you can also place the variables from .env directly into the MCP server configuration.

Available Tools

list_music_library

Scans MUSIC_LIBRARY_URL and returns the discovered song names and URLs.

play_music

Plays a specified song. You can pass:

• url: Play this URL directly

• song_name: Find and play by name from the music library

If both url and song_name are passed, url takes precedence.

play_song_from_library

Finds and plays from the music library using only song_name.

play_playlist

Plays the music library list sequentially.

It first writes the list to an MQTT retained topic:

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

Then sends the following to MQTT_TOPIC:

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

Once the ESP32-C3 receives this, it will start playing from the list cached locally, and play the next song automatically after the current one finishes. This way, the MCP server does not need to stay online.

Parameters:

• start_index: Which song to start from, default 0

• max_songs: Maximum number of songs to cache and play, default MAX_PLAYLIST_ITEMS

next_music

Next track or switch track.

• Pass url or song_name: Switch directly to the specified song, maintaining the original single-track playback logic

• Pass no parameters: Sends playlist_next, allowing the ESP32-C3 to skip to the next track in playlist mode

pause_music

Pauses playback. The ESP32-C3 will stop current playback but retain the last URL.

stop_music

Stops playback and clears the last URL. Playlist mode will also be exited.

set_volume

Sets the volume, range 0-100.

reset_wifi

Sends:

{"action":"reset_wifi"}

Once the ESP32-C3 receives this, it will clear the saved Wi-Fi configuration and restart, enabling the mobile provisioning hotspot after reboot.

Note: This tool requires the ESP32-C3 to be currently online and connected to MQTT. If the device is already offline, it will not receive this MQTT message and must wait for the firmware to automatically enable the provisioning hotspot after a connection failure.

MQTT Message Convention

The control topic defaults to:

esp32-c3/music/play

Common control messages:

{"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"}

The playlist topic default prefix is:

esp32-c3/music/playlist/active

The MCP server will publish retained messages, which the ESP32-C3 subscribes to:

esp32-c3/music/playlist/active/#

Local Checks

Check Node.js syntax:

node --check index.js

Currently, package.json does not have automated test scripts.