About Stackchan MCP
Stackchan MCP is an MCP server in the IoT category: mCP gateway for StackChan (xiaozhi-esp32): bridge any MCP client to a CoreS3 + servo + camera robot.
Install
From source
git clone https://github.com/kisaragi-mochi/stackchan-mcpThis server has no ConduID identity, so agent calls to it are not receipted. Pin the version you install and review the source before granting it credentials.
Tools (27)
beat_clip_save(seconds?)Save the latest rolling beat-mode audio window as a 16 kHz mono WAV temp file and return its path plus actual captured duration. Clip files persist on disk; the caller is responsible for deleting them when no longer needed.
Parameters not published.
beat_meta_snapshot()Poll the latest beat-mode metadata: active state, BPM, confidence, active sensitivity/minimum onset floor, last beat/audio timestamps, capture health, counters, and current motion/LED parameters.
Parameters not published.
beat_mode_start(motion_intensity?, sensitivity?, color?, duration_sec?)Start gateway-only beat mode: continuously capture ambient device audio through the existing `listen` wire path, estimate BPM in the gateway, and drive free-running beat-synced head sway plus base-ring LED flashes. `sensitivity` tunes the onset floor for quiet rooms or loud venues. Beat mode requests the firmware raw capture profile so music bypasses speech-oriented AFE suppression. While active, `listen()` is mutually exclusive; `say()` may interrupt and beat mode re-arms listening afterwards. Requires the `[stt]` extra for Opus decoding.
Parameters not published.
beat_mode_stop()Stop beat mode and send `listen.stop` best-effort while retaining the latest rolling audio buffer for clip export until the next beat-mode start or gateway restart.
Parameters not published.
beat_mode_update(motion_intensity?, sensitivity?, color?, blink_rate?, motion_enabled?, led_enabled?)Update beat-mode VJ parameters without restarting capture.
Parameters not published.
check_vm_enCheck servo power supply (VM EN HIGH) state
Parameters not published.
clear_ledsTurn all 12 base RGB LEDs off
Parameters not published.
get_device_infoESP32 device state (battery / volume / WiFi / etc.)
Parameters not published.
get_statusGateway connection state
Parameters not published.
get_touch_sensor_enabledRead whether head-touch detection is enabled. The NVS-backed setting persists across reboot.
Parameters not published.
Show all 27 tools
get_touch_stateTouch sensor state (press / release / stroke / etc.)
Parameters not published.
listen(duration_ms?, engine?, language?, model?, motion?, look_up_pitch?)Capture a short utterance from the device microphone and transcribe it via gateway-side STT. Default engine: **faster-whisper** (local, MIT) — see [STT setup](#optional-stt-setup-faster-whisper). Optional `motion` feedback can show the `thinking` face or tilt the head up during capture. Requires the `[stt-faster-whisper]` (or `[stt-openai]`) extra and a firmware update with the inbound `listen` wire type.
Parameters not published.
move_head(yaw, pitch, speed?)Move the neck (servos). `pitch` is constrained to `5..85` — the M5Stack-recommended operating range. For the wider firmware hard clamp (`0..88`), use the firmware-side `set_head_angles` device tool instead.
Parameters not published.
say(text, voice?, speaker_id?, reference_audio?)Speak text on the device speaker via gateway-side TTS. A supported expression emoji in the text can switch the avatar face in the same call. Default engine: **VOICEVOX** (runs as a separate HTTP service — see [TTS setup](#optional-tts-setup-voicevox)). Requires the `[tts]` extra.
Parameters not published.
set_all_leds(r, g, b)Set all 12 base RGB LEDs to the same color
Parameters not published.
set_avatar(face)Switch avatar expression (`idle` / `happy` / `thinking` / `sad` / `surprised` / `embarrassed`), or `off` to hide the avatar and disable blink so the underlying WiFi config / OTA / settings screens are visible. Any other face brings the avatar back and restores blink.
Parameters not published.
set_blink(state)Blink on/off
Parameters not published.
set_brightness(brightness)Screen brightness (0-100)
Parameters not published.
set_led(index, r, g, b)Set one of the 12 base RGB LEDs (index `0..11`, channels `0..255`)
Parameters not published.
set_leds(colors)Batch-set the first N LEDs from a `[[r,g,b], ...]` array in a single I2C burst (use this for animations / multi-color patterns); trailing LEDs keep their previous color
Parameters not published.
set_mouth(state)Mouth open/close (one-shot, held until next call)
Parameters not published.
set_mouth_sequence(steps)Queue and play a list of `{shape, duration_ms}` steps locally for TTS lip-sync — no per-step WebSocket RTT jitter
Parameters not published.
set_touch_sensor_enabled(enabled)Enable or disable head-touch detection. Disabling stops both the firmware local motion response and MCP `stackchan/event` emission, and persists across reboot.
Parameters not published.
set_volume(volume)Speaker volume (0-100)
Parameters not published.
stackchan_follow_led_stream(action, url, target, ...)Subscribe to an arbitrary external WebSocket LED-frame stream and forward validated `colors` frames to either the built-in 12-LED base ring or a Port B WS2812 strip. `event` frames bypass the rate gate; `continuous` frames are capped by `max_fps`.
Parameters not published.
stackchan_follow_pose_stream(action, url, ...)Subscribe to an arbitrary external WebSocket pose-stream and drive the head to follow incoming `yaw` / `pitch` frames 1:1 within the SCS0009 working range. `action` switches between `start` / `stop` / `status`. Includes per-axis flip, pitch-center offset, downsample rate cap, angular-velocity clamp, and reconnect with exponential backoff; the initial pose is seeded from the device so the angular-velocity clamp is anchored at the real servo position from the first frame. The upstream server's protocol (zero-offset commands, source dispatching, transport) is intentionally outside this gateway's scope.
Parameters not published.
take_photo(question?)Capture a frame, save as JPEG, return the path + inline image block
Parameters not published.
Ask AI
✦
Ask AI about Stackchan MCP
Powered by Claude · Grounded in docs
I know everything about Stackchan MCP. Ask me about installation, configuration, usage, or troubleshooting.
Security checks
6 checks have not been run yet.