stackchan-mcp を試す

「stackchan-mcp」を試してみたのでまとめました。

1. stackchan-mcp

M5Stack版 StackChan を、PC上のAIツールやMCPクライアントから操作したい場合に使えるのが stackchan-mcp です。

stackchan-mcp は、MCPクライアントと StackChan の間に入るゲートウェイです。
構成は次のようになります。

MCPクライアント側からは、StackChan を操作するためのツールが見えるようになり、首を動かす、カメラ画像を撮る、表情を変える、音量や明るさを変える、といった操作をAIツールから呼び出せます。

2. できること

stackchan-mcp では、主に次のような操作ができます。

3. ファームウェアを書き込む

まず、StackChan 側に対応ファームウェアを書き込みます。
初心者向けには、ビルド済みバイナリを使う方法が簡単です。

(1) GitHub の Releases から最新の firmware-v* を開き、merged-binary.bin をダウンロード。

(2) USBポートの確認。

ls /dev/cu.*

(3) esptoolのインストール。

python -m venv .venv
source .venv/bin/activate
python -m pip install esptool

(4) esptool で書き込む。

esptool.py --chip esp32s3 --port /dev/cu.usbmodem2101 -b 460800 \
    write_flash 0x0 merged-binary.bin

ポート名は環境によって変わるので、自分のPCで認識されているデバイス名に置き換えます。

4. Wi-Fiとgateway URLの設定

(1) StackChan を起動。

(2) スマートフォンで Wi-Fiアクセスポイント「Xiaozhi-0365」に接続し、ブラウザで http://192.168.4.1 にアクセス。

(3) 詳細設定タブで、WebSocket Gateway URL を設定。

ws://PCのLAN内IPアドレス:8765/

外部公開する場合はゲートウェイトークンも設定した方が安全です。

(4) Wi-Fi設定タブでWi-Fiを設定。

(5) StackChan を再起動。
顔が表示されます。

5. gateway のインストール

(1) stackchan-mcp gateway のインストール。

uv tool install stackchan-mcp

(2) gateway を起動。
VISION_HOST は、PCのLAN内IPアドレスにします。ゲートウェイトークンを設定した場合は、STACKCHAN_TOKENも指定します。

export STACKCHAN_TOKEN="your-secret-token-here" 
export VISION_HOST="192.168.1.23"

stackchan-mcp

PC側に WebSocket サーバとHTTPキャプチャサーバが立ち上がります。

標準のポートは次の通りです。

WebSocket: 8765
HTTP capture: 8766

StackChan は 8765 に接続し、カメラ画像は 8766 の /capture に送られます。

(3) Ctrl+C  でgatewayを終了。

6. MCPクライアントの設定

(1) Claude Desktop を使う場合は次のように指示。

Claude Desktop に stackchan-mcp を追加して。

{
  "mcpServers": {
    "stackchan-mcp": {
      "type": "stdio",
      "command": "stackchan-mcp",
      "env": {
        "STACKCHAN_TOKEN": "your-secret-token-here",
        "VISION_HOST": "192.168.1.23"
      }
    }
  }
}

VISION_HOST は、PCのLAN内IPアドレスにします。ゲートウェイトークンを設定した場合は、STACKCHAN_TOKENも指定します。

(2) Claude Desktopの再起動。

7. 接続確認

(1) 接続確認。

関連