MCP gateway for StackChan (xiaozhi-esp32): bridge any MCP client to a CoreS3 + servo + camera robot
stackchan-mcp
M5Stack 公式 StackChan (2025年 Kickstarter 出荷キット) を任意の LLM クライアントから操作するための MCP (Model Context Protocol) ブリッジ。
オリジナルの stack-chan プロジェクト (タカヲさん) のコミュニティから生まれ、M5Stack 公式が製品化した StackChan キットを対象としています。
┌─────────────┐ stdio MCP ┌──────────────┐ WebSocket MCP ┌──────────────┐
│ MCP client │ ─────────────────▶ │ gateway │ ──────────────────▶ │ ESP32 (CoreS3│
│ (Claude等) │ ◀───────────────── │ (Python) │ ◀────────────────── │ +StackChan) │
└─────────────┘ │ │ └──────────────┘
│ /capture │ ◀── HTTP POST (JPEG) ──┘
└──────────────┘
任意の MCP クライアント (Claude Code / Claude Desktop / 他) から、首振り・カメラ撮影・タッチセンサ・アバター表情切替などの StackChan 操作を呼び出せる。
構成
このリポジトリはモノレポ。
| ディレクトリ | 内容 |
|---|---|
| firmware/ | 78/xiaozhi-esp32 フォーク全体（git subtree）。StackChan 用カスタムボードは firmware/main/boards/stackchan/ に配置 |
| gateway/ | Python MCP ゲートウェイ。stdio MCP サーバー (LLM側) + WebSocket MCP クライアント (ESP32側) + HTTP capture サーバー |
| docs/ | architecture.md: 全体構成図・ツール名マッピング・写真フロー・認証・Phase ロードマップ |
想定ハードウェア
M5Stack 公式 StackChan キット (Kickstarter 2025 出荷版)。公式ドキュメントの出荷時ファームウェアを本リポジトリの firmware で置き換える形で動作します。
| 部品 | 仕様 | |---|---| | 本体 | M5Stack CoreS3 (ESP32-S3, 16MB Flash, 8MB PSRAM) | | 首サーボ | SCS0009 ×2 (yaw + pitch、シリアルバス、TX=GPIO6, RX=GPIO7) | | カメラ | GC0308 (DVP, 320×240 YUV422) | | タッチ | FT6336 / Si12T | | ディスプレイ | ILI9342 (SPI, 320×240) |
自作の stack-chan (タカヲさん版オリジナル設計) でも、上記のピンアサイン・I2C アドレスが一致していれば動く可能性があります。動作報告・修正 PR 歓迎です。
ツール一覧 (gateway 経由で MCP クライアントが呼べる)
| ツール | 説明 | 状態 |
|---|---|---|
| get_status | ゲートウェイ接続状態 | ✅ |
| get_device_info | ESP32 デバイス状態 (バッテリー/音量/WiFi 等) | ✅ |
| take_photo(question?) | カメラ撮影 → JPEG 保存 → パス返す | ✅ |
| set_volume(volume) | スピーカー音量 (0-100) | ✅ |
| set_brightness(brightness) | 画面明るさ (0-100) | ✅ |
| move_head(yaw, pitch, speed?) | 首を動かす (サーボ) | ✅ |
| get_touch_state | タッチセンサ状態 (press/release/stroke 等) | ✅ |
| set_avatar(face) | アバター表情切替 (neutral/happy/sad 等 6種) | ✅ |
| set_blink(state) | 瞬き ON/OFF | ✅ |
| set_mouth(state) | 口開閉 | ✅ |
| check_vm_en | サーボ電源 (VM EN HIGH) 状態確認 | ✅ |
詳細スキーマは gateway/README.md 参照。
クイックスタート
1. ファームウェア書き込み (CoreS3)
cd firmware
docker run --rm -v $PWD:/project -w /project espressif/idf:v5.5.2 \
python ./scripts/release.py stackchan
# → releases/v2.2.6_stackchan.zip
# フラッシュ (CoreS3 を USB 接続後)
esptool.py --chip esp32s3 --port /dev/cu.usbmodem1101 -b 460800 \
write_flash 0x0 build/merged-binary.bin
WiFi 設定は ESP32 が起動後にスマホで設定 UI に接続して行う (xiaozhi-esp32 標準フロー)。
2. ゲートウェイ起動
cd gateway
cp .env.example .env # STACKCHAN_TOKEN / VISION_HOST を設定
uv sync
uv run python -m stackchan_mcp
3. MCP クライアント登録 (Claude Code 例)
~/.claude.json に追加:
{
"mcpServers": {
"stackchan-mcp": {
"type": "stdio",
"command": "uv",
"args": [
"run", "--directory", "/path/to/stackchan-mcp/gateway",
"python", "-m", "stackchan_mcp"
]
}
}
}
詳細は gateway/README.md 参照。
アバター画像について
firmware/main/boards/stackchan/avatar_images.cc は 真っ黒 RGB565 のプレースホルダ です。ビルドは通りますが、画面には何も表示されません。実際にアバターを表示するには、自分の PNG 画像 (160×120) から avatar_images.cc を再生成してください。
シンボル一覧 (avatar_images.h 参照):
- 表情系 (6):
avatar_idle,avatar_happy,avatar_thinking,avatar_sad,avatar_surprised,avatar_embarrassed - 目 (3):
avatar_eyes_open,avatar_eyes_half,avatar_eyes_closed - 口 (5):
avatar_mouth_closed,avatar_mouth_half,avatar_mouth_open,avatar_mouth_e,avatar_mouth_u
PNG → RGB565 配列の変換スクリプトは LVGL 公式の Online Image Converter などが使えます。
既知の課題
- 大角度急逆転 (±60° → -60° 等) でサーボハングする場合あり (Motion::update_task の補間移植で改善予定)
- タッチセンサ (Si12T) のぽん判定取りこぼし (感度レジスタ調整余地)
ライセンス
このリポジトリはデュアルライセンス構成です。
| 範囲 | ライセンス |
|---|---|
| 全体 (gateway/, トップレベル, firmware/ の大部分) | MIT License (LICENSE 参照) |
| firmware/main/boards/stackchan/ 内の SCServo_lib 由来ファイル (SCS.{cc,h}, SCSCL.{cc,h}, SCSerial.{cc,h}, INST.h, SCServo.h) | GNU GPL-3.0 (firmware/main/boards/stackchan/SCServo_lib_LICENSE.txt 参照) |
これは Feetech の SCServo SDK が GPL-3.0 で配布されているための制約です。SCServo_lib を静的リンクする firmware バイナリ全体は実質 GPL-3.0 として配布されることになります。
一方、gateway/ は独立した Python プロセスで、ESP32 とはネットワーク経由 (WebSocket) でしか通信しないため、MIT License のまま利用・派生できます。
upstream
firmware/ は 78/xiaozhi-esp32 (MIT) のフォーク (kisaragi-mochi/xiaozhi-esp32) を git subtree で取り込んでいます。SCServo_lib は公式 stack-chan (タカヲさん) から移植したファームウェアコンポーネントです。
関連プロジェクト
- M5Stack 公式 StackChan ドキュメント — 想定ハードウェアの公式ドキュメント (出荷時ファーム / 配線図 / API リファレンス等)
- xiaozhi-esp32 — ベースとなる ESP32 LLM クライアントファームウェア
- stack-chan — オリジナルの StackChan プロジェクト (タカヲさん)
- Model Context Protocol — MCP プロトコル仕様
コントリビューション
Issue / PR 歓迎です。StackChan コミュニティで使える形を目指しています。