What is stackchan-mcp?
stackchan-mcp, from the GitHub user kisaragi-mochi, turns the official M5Stack StackChan kit (the 2025 Kickstarter version, built on an M5Stack CoreS3) into a body for an MCP client. It replaces the kit's factory firmware with a build of xiaozhi-esp32 and adds a Python gateway that is a stdio MCP server on one side and a WebSocket server for the robot on the other. The README lists 30 tools: head movement on two neck servos, photos from the 320×240 camera, touch reads, avatar faces, mouth and blink, the 12 base LEDs, speech, listening and a beat-following music mode.
The gateway is on PyPI as stackchan-mcp and is MIT-licensed; the firmware links a GPL-3.0 servo library, so the firmware build is effectively GPL-3.0. The repository has about 184 stars, released gateway v0.20.0 and firmware-v1.18.0 on 23 October 2026, and had commits in November 2026.
How to install stackchan-mcp
uv tool install stackchan-mcpIs stackchan-mcp worth it?
The physical stakes here are low and the project treats them seriously anyway. The only moving parts are two SCS0009 neck servos. The gateway rejects move_head calls outside yaw -90 to 90 and pitch 5 to 85 degrees, M5Stack's recommended range, and the firmware clamps pitch to 0 to 88 at every servo write, so a call that skips the gateway still cannot drive the head past the limit validated on real hardware. The pose-following mode adds an angular-velocity clamp and caps commands at 20 per second. Everything else the agent controls is a screen, LEDs, a speaker and a microphone.
Those last two are the bigger consideration. listen records from the robot's microphone and transcribes it, by default with faster-whisper on your own machine and optionally with OpenAI's API; take_photo sends the camera frame to your model provider. The upgrade_firmware tool can reflash the robot over Wi-Fi, though the gateway first checks that the file is a StackChan image with a valid SHA-256 and the device keeps a rollback slot.
The catch: the gateway's robot-facing side listens on 0.0.0.0, port 8765 for the WebSocket and 8766 for photo uploads and firmware downloads, and if STACKCHAN_TOKEN is not set it logs a warning and accepts any client. Set the token on both the gateway and the robot before first use. There is no simulator; testing means the real kit, which is forgiving. Setup involves flashing with esptool over USB, configuring Wi-Fi through the robot's captive portal and, for speech, running VOICEVOX as a separate service.
Our take: for anyone who owns the kit, this is the most complete MCP route we have read, with a changelog that records hardware-validated fixes in unusual detail. It suits a hobbyist or researcher exploring embodied agents, not a classroom of unattended devices on a shared network.
Where it earns its place
A developer building a voice-first assistant prototype
Give a coding agent a desk presence that speaks status updates and looks up when spoken to
Run the gateway with local VOICEVOX and faster-whisper so audio stays on the machine, and let the agent call say and set_avatar when long jobs finish. Software costs nothing; model tokens are the bill.
An HCI researcher studying embodied agents
Run sessions where an agent reacts to touch, sound and what it sees
Enable the head-touch sensor, log stackchan/event notifications and pair take_photo with listen. Set STACKCHAN_TOKEN and keep the robot on an isolated network for participant sessions.
A maker who streams music sessions
Have the robot nod and flash its LEDs in time with the room
Start beat_mode_start with a motion intensity and colour; the gateway estimates BPM from the microphone and drives head sway and the 12 base LEDs without the model in the loop.
Before you commit
- Setup
- Flash merged-binary.bin from the latest firmware release with esptool.py over USB, join Wi-Fi through the captive portal, install the gateway with uv tool install stackchan-mcp, set STACKCHAN_TOKEN on both sides, then add stackchan-mcp to your client as a stdio server. Speech needs the tts extra and a VOICEVOX service.
- Integrations
- M5Stack StackChan kit (CoreS3, SCS0009 servos, GC0308 camera); VOICEVOX by default, with Irodori, ElevenLabs and Fish Audio TTS options; faster-whisper or OpenAI for speech-to-text; mDNS discovery; optional Tailscale Funnel or a Cloudflare relay for off-LAN use.
- Data and privacy
- Photos and transcripts go to your model provider through the client; audio is transcribed locally unless you pick the OpenAI engine. The gateway listens on 0.0.0.0:8765 and 8766 for the robot and accepts any client without STACKCHAN_TOKEN; its optional HTTP MCP endpoint defaults to 127.0.0.1.
- Cost at scale
- Free software. Cloud TTS or OpenAI transcription are billed by those providers if you choose them; the default local engines cost nothing beyond the hardware.
- Limits
- Only the official M5Stack kit is targeted; self-built StackChans need matching pins. mDNS discovery fails on networks that block multicast. About 80 open issues and pull requests.
What’s good
- Gateway and firmware both clamp head angles
- 30 tools across motion, camera, audio, face and LEDs
- Local speech-to-text by default with faster-whisper
- Over-the-air firmware updates with image checks and rollback
What’s not
- Accepts any client on 0.0.0.0 until a token is set
- Replaces the kit's factory firmware
- Microphone and camera access by design
- Only the official M5Stack kit is targeted
Best for
Owners of the M5Stack StackChan kit who want an agent with a face, a voice and a camera on their desk.
stackchan-mcp alternatives
stackchan-mcp: common questions
- Is stackchan-mcp worth it?
- A carefully engineered way to give an agent a small physical presence on your desk, with real limits on the servos and a network default you should tighten before you plug it in. We rate it 3.8 out of 5.
- How much does stackchan-mcp cost?
- Free and open source: the gateway is MIT, the firmware build effectively GPL-3.0. You need the M5Stack StackChan kit.
- What are the downsides of stackchan-mcp?
- Accepts any client on 0.0.0.0 until a token is set; replaces the kit's factory firmware; microphone and camera access by design; only the official M5Stack kit is targeted.
- Who is stackchan-mcp best for?
- Owners of the M5Stack StackChan kit who want an agent with a face, a voice and a camera on their desk.
- How much does stackchan-mcp cost for a team or in production?
- Free software. Cloud TTS or OpenAI transcription are billed by those providers if you choose them; the default local engines cost nothing beyond the hardware.
- Is stackchan-mcp safe for company data?
- Photos and transcripts go to your model provider through the client; audio is transcribed locally unless you pick the OpenAI engine. The gateway listens on 0.0.0.0:8765 and 8766 for the robot and accepts any client without STACKCHAN_TOKEN; its optional HTTP MCP endpoint defaults to 127.0.0.1.
- What are the best stackchan-mcp alternatives?
- The closest alternatives we have reviewed are ROS MCP Server and WLKATA MT4 control stack.
Answers checked Nov 16, 2026.