xiaozhi-esp32: An ESP32 Voice Chatbot That Puts MCP on the Device
Project brief: An MCP-based chatbot | MCP . The previous 157-variant baseline was validated on ESP-IDF v6.0.1; the current matrix contains 171 variants, of which 170 support IDF 6.0.x and the ESP32-S31 variant requires IDF 6.1 or later.
At a glance
- What is it?
- xiaozhi-esp32 turns ESP32 boards into voice-controlled AI assistants using MCP for device and cloud control. It supports 171 board variants, but the IDF 6 migration and hardware complexity demand careful selection.
- Who is it for?
- Adopt xiaozhi-esp32 if you need a voice-controlled ESP32 assistant with MCP-based device control and are willing to handle ESP-IDF 6 setup and board-specific hardware. Avoid it if you want a plug-and-play product or lack experience with ESP-IDF and audio pipelines.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 1 day ago.
- What is it written in?
- Mainly C++, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 13, 2026, and from our analysis. They are not legal advice.
Star history
- 78/xiaozhi-esp3233,180 ★ · +4,541
| Repository | 2026-08-04 | 2026-11-13 |
|---|---|---|
| 78/xiaozhi-esp32 | 28.6k | 33.2k |
4,541 Stars in the last 101 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
What Problem It Solves
The core problem is that voice assistants typically run in the cloud, leaving the device as a dumb microphone and speaker. xiaozhi-esp32 flips that by putting MCP on both sides. Cloud-side MCP extends model capabilities to smart home control, PC desktop operation, and knowledge search, while device-side MCP gives the model direct access to hardware. This dual-MCP approach is what distinguishes it from a simple wake-word and streamer. For an engineer, the value is in the abstraction: you can add a new sensor or actuator by defining an MCP tool. The trade-off is that you need to understand MCP, ESP-IDF, and the audio pipeline to make it work.
Architecture: From Audio to MCP
The MCP layer is where the architecture gets interesting. Device-side MCP exposes hardware control as tools, and cloud-side MCP connects to external services. The README lists examples like smart home control and PC desktop operation. The audio pipeline concurrency and MQTT/UDP packet validation are noted as recent hardening, which implies these were problem areas. The README lists two communication transports, WebSocket and MQTT + UDP.
Getting It Running: Flashing and Building
The release matrix contains 171 variants, of which 170 support IDF 6.0.x. One variant, labeled ESP32-S31, requires IDF 6.1 or later. That is a critical detail: if you own that specific board, you cannot use the 6.0.x SDK. The previous baseline of 157 variants was validated on IDF v6.0.1, and the current matrix has been hardened for release-matrix selection. Before building, you must verify that your board is in the matrix and that its variant does not require a newer IDF. For beginners, the README recommends firmware that can be flashed without setting up a development environment.
Hardware Support and Its Limits
A genuine limitation is the hardware dependency for full-duplex interaction. The README states that realtime full-duplex requires AEC-capable hardware. If your board lacks AEC, you get half-duplex, which means the device cannot listen while it speaks. That changes the user experience significantly. Also, the ESP32-S31 variant's IDF 6.1 requirement means you cannot use the same toolchain for all boards. If you have a mixed fleet of devices, you may need multiple IDF versions installed. The project's reliance on ESP-SR for wake words also ties you to Espressif's library, which may have its own licensing or version constraints.
Licensing and Maintenance Costs
The upgrade cost is not just firmware. The README mentions that audio pipeline concurrency and release-matrix selection have been hardened, which indicates these were areas of bug fixes. If you maintain a custom board, you must track changes to the board definition files. For a production deployment, you would need to pin a specific release and test thoroughly. The MIT license gives you freedom, but the project's complexity means you are responsible for your own support.
Alternatives and When to Choose Them
One alternative is to use a Linux-based voice assistant on a Raspberry Pi, which has more processing power and memory. That approach allows you to run larger models locally, but it loses the low-power, real-time capabilities of an ESP32. The trade-off is power consumption and cost versus capability. If you need a battery-powered wearable or a small embedded device, xiaozhi-esp32 is the right fit. If you need heavy local processing or extensive cloud integration, a Pi or a dedicated voice assistant might be better. The choice depends on your hardware constraints and whether you need MCP integration. The project's MCP focus is its unique selling point, but it is also a reason to avoid it if you do not plan to use MCP.
Editorial conclusion
Adopt xiaozhi-esp32 if you need a voice-controlled ESP32 assistant with MCP-based device control and are willing to handle ESP-IDF 6 setup and board-specific hardware. Avoid it if you want a plug-and-play product or lack experience with ESP-IDF and audio pipelines. Before committing, verify your exact board is in the 171-variant release matrix, confirm whether it needs IDF 6.1 (like the ESP32-S31 variant). The project is active and MIT-licensed, but its value depends entirely on matching your hardware to the supported list.
Frequently asked questions
What can Xiaozhi AI do?
It is voice chatbot firmware for ESP32 boards. The listed capabilities include offline wake-up with customisable wake words, Opus audio streaming with both a conventional recognition, model and speech pipeline and realtime end to end voice models, full duplex interaction on hardware with echo cancellation, speaker recognition, displays with emoji, camera input on supported boards, 39 interface languages, several networking options including 4G modules, and provisioning over a hotspot or Bluetooth.
What does ESP32 stand for?
The README lists the chip platforms it builds for: the ESP32, the C3, the C5, the C6, the S3 and the P4, plus a further variant called the S31 that appears in the configuration files and in the SDK requirement rather than in the feature list.
Can ESP32 run AI?
Part of it, and the file is specific about which part. Wake-up detection runs offline on the board using Espressif's speech recognition library, and audio is encoded there, but the model work happens on a server the firmware connects to, with Qwen and DeepSeek named as the models. Personal users can register an account to use the Qwen realtime model for free.
Can ChatGPT program an ESP32?
That is a general question rather than one about this project. The code is C++ firmware built with the Espressif SDK, with a CMake file, per chip configuration files, a custom board guide and a set of protocol documents.
xiaozhi esp32 vscode
VSCode is one of two editors the project names, the other being Cursor, and the instruction is to install the Espressif plugin for the SDK. The minimum SDK is 6.0.1 with 6.1 recommended, the 5.x line is not supported, and the file advises Linux over Windows for faster compilation and fewer driver problems.
xiaozhi esp32 alternative
The README points to its own pieces rather than alternatives: the official xiaozhi.me server, a web-based Custom Assets Generator, and Feishu documents with the breadboard and flashing tutorials.
Official sources
Was this useful?