ESP32-C3 MCP Music Server
ESP32-C3 MCP Music Server
このプロジェクトのルートディレクトリはMCPサーバーであり、OpenClaw、Claude Desktop、またはその他のMCPエージェントが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ブローカー
ESP32-C3クライアントが書き込み済みで、同じMQTTブローカーに接続されていること
HTTP音楽ディレクトリ(例:nginxで公開されたMP3ファイルディレクトリ)
インストール
npm install環境変数テンプレートをコピーします:
copy .env.example .envWindows 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"}プレイリストトピックのデフォルトプレフィックスは:
esp32-c3/music/playlist/activeMCPサーバーはretainedメッセージをパブリッシュし、ESP32-C3がサブスクライブします:
esp32-c3/music/playlist/active/#ローカルチェック
Node.jsの構文をチェックします:
node --check index.js現在 package.json に自動テストスクリプトはありません。
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.