ESP32-C3 MCP Music Server

Корневой каталог этого проекта представляет собой MCP-сервер, предназначенный для управления воспроизведением музыки на аудиоклиенте ESP32-C3 через MQTT с помощью OpenClaw, Claude Desktop или других MCP-агентов.

Инструкции по прошивке ESP32-C3 находятся в esp32-c3-client/README.md.

Функции

Отправка команд управления (воспроизведение, пауза, стоп, громкость, следующая песня и т.д.) на ESP32-C3 через MQTT
Чтение списка песен из HTTP-каталога музыки
Поддержка поиска и воспроизведения по названию песни
Поддержка последовательного воспроизведения всего списка музыки
Поддержка записи плейлиста в MQTT retained topic для автономного воспроизведения на ESP32-C3
Поддержка сброса сохраненных настроек Wi-Fi на ESP32-C3 для повторного входа в режим настройки через смартфон

Требования

Node.js 18 или выше
Доступный MQTT-брокер
Клиент ESP32-C3 прошит и подключен к тому же MQTT-брокеру
HTTP-каталог музыки, например, директория с MP3-файлами, опубликованная через nginx

Установка

npm install

Скопируйте шаблон переменных окружения:

copy .env.example .env

В Windows PowerShell также можно использовать:

Copy-Item .env.example .env

Затем измените .env в соответствии с вашей конфигурацией.

Переменные окружения

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

Описание:

MQTT_BROKER: Адрес подключения к MQTT-брокеру, поддерживаются URL с именем пользователя и паролем
MQTT_TOPIC: Топик, в который ESP32-C3 получает команды управления
MQTT_PLAYLIST_TOPIC: Префикс для retained-топика кэша плейлиста
MUSIC_LIBRARY_URL: Адрес HTTP-каталога музыки, в конце можно не ставить /
FETCH_TIMEOUT_MS: Тайм-аут для получения каталога музыки или файлов плейлиста
MAX_PLAYLIST_FETCHES: Максимальное количество анализируемых файлов плейлистов
MAX_PLAYLIST_ITEMS: Максимальное количество песен, кэшируемых при последовательном воспроизведении

Пример конфигурации MCP

В агентах, поддерживающих MCP stdio server, настройте команду следующим образом:

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

Если агент поддерживает переменные окружения, можно также поместить переменные из .env непосредственно в конфигурацию MCP-сервера.

Доступные инструменты

`list_music_library`

Сканирует MUSIC_LIBRARY_URL и возвращает список найденных названий песен и их URL.

`play_music`

Воспроизводит указанную песню. Можно передать:

url: Воспроизвести этот URL напрямую
song_name: Найти и воспроизвести по названию из музыкальной библиотеки

Если переданы и url, и song_name, приоритет отдается url.

`play_song_from_library`

Поиск и воспроизведение только по song_name из музыкальной библиотеки.

`play_playlist`

Последовательное воспроизведение списка музыкальной библиотеки.

Сначала список записывается в MQTT retained topic:

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

Затем в MQTT_TOPIC отправляется:

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

После получения ESP32-C3 начинает воспроизведение из локально кэшированного списка, автоматически переходя к следующей песне после завершения текущей. Таким образом, MCP-серверу не нужно быть постоянно онлайн.

Параметры:

start_index: С какой песни начать, по умолчанию 0
max_songs: Максимальное количество песен для кэширования и воспроизведения, по умолчанию MAX_PLAYLIST_ITEMS

`next_music`

Следующая песня или переключение трека.

Передача url или song_name: Прямое переключение на указанную песню, сохраняя логику воспроизведения одного трека
Без параметров: Отправка playlist_next, чтобы ESP32-C3 перешел к следующей песне в режиме плейлиста

`pause_music`

Приостановка воспроизведения. ESP32-C3 остановит текущее воспроизведение, но сохранит последний URL.

`stop_music`

Остановка воспроизведения и очистка последнего URL. Режим плейлиста также будет завершен.

`set_volume`

Установка громкости, диапазон 0-100.

`reset_wifi`

Отправка:

{"action":"reset_wifi"}

После получения ESP32-C3 очистит сохраненные настройки Wi-Fi и перезагрузится, после чего откроет точку доступа для настройки через смартфон.

Примечание: этот инструмент требует, чтобы ESP32-C3 оставался онлайн и был подключен к MQTT. Если устройство уже оффлайн, оно не получит это сообщение MQTT, и придется дождаться автоматического включения точки доступа после неудачного подключения прошивки.

Соглашение о сообщениях MQTT

Топик управления по умолчанию:

esp32-c3/music/play

Типовые сообщения управления:

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

Префикс топика плейлиста по умолчанию: