ESP32-C3 MCP Music Server

这个项目的根目录是 MCP 服务器，用来让 OpenClaw、Claude Desktop 或其他 MCP agent 通过 MQTT 控制 ESP32-C3 音频客户端播放音乐。

ESP32-C3 固件说明在 esp32-c3-client/README.md。

功能

• 通过 MQTT 向 ESP32-C3 下发播放、暂停、停止、音量、下一首等控制指令
• 从 HTTP 音乐目录读取歌曲列表
• 支持按歌曲名搜索并播放
• 支持顺序播放整个音乐列表
• 支持把播放列表写入 MQTT retained topic，由 ESP32-C3 自己按顺序播放
• 支持清除 ESP32-C3 已保存的 Wi-Fi 配置并重新进入手机配网模式

运行要求

• Node.js 18 或更高版本
• 一个可访问的 MQTT broker
• ESP32-C3 客户端已烧录并连接到同一个 MQTT broker
• 一个 HTTP 音乐目录，例如 nginx 暴露的 MP3 文件目录

安装

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 broker 连接地址，支持带用户名密码的 URL
• MQTT_TOPIC: ESP32-C3 接收控制指令的 topic
• MQTT_PLAYLIST_TOPIC: 播放列表 retained 缓存 topic 前缀
• MUSIC_LIBRARY_URL: HTTP 音乐目录地址，末尾可以不带 /
• FETCH_TIMEOUT_MS: 拉取音乐目录或播放列表文件的超时时间
• MAX_PLAYLIST_FETCHES: 最多解析多少个播放列表文件
• MAX_PLAYLIST_ITEMS: 顺序播放时最多缓存多少首歌

MCP 配置示例

在支持 MCP stdio server 的 agent 中，把命令配置为：

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

如果 agent 支持环境变量，也可以把 .env 里的变量直接放到 MCP server 配置里。

可用工具

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 消息约定

控制 topic 默认是：

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

播放列表 topic 默认前缀是：

esp32-c3/music/playlist/active

MCP 服务器会发布 retained 消息，ESP32-C3 订阅：

esp32-c3/music/playlist/active/#

本地检查

检查 Node.js 语法：

node --check index.js

当前 package.json 还没有自动化测试脚本。