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

プレイリストトピックのデフォルトプレフィックスは：

esp32-c3/music/playlist/active

MCPサーバーはretainedメッセージをパブリッシュし、ESP32-C3がサブスクライブします：

esp32-c3/music/playlist/active/#

ローカルチェック

Node.jsの構文をチェックします：

node --check index.js

現在 package.json に自動テストスクリプトはありません。