Skip to content
Get packs

XiaoZhi

Open-source firmware that turns ESP32 boards into a voice chatbot controllable through MCP.78/xiaozhi-esp32

GitHub Download v2.5.2
Stars
32.5k
Forks
7.6k
Licence
MIT
Language
C++
Last update
5 days ago
Type
App

What it is

XiaoZhi is open-source firmware for small ESP32-family microcontroller boards that makes them into a voice assistant. It combines speech recognition, a large language model and speech output, and uses the MCP protocol so the assistant can also control devices and connect to outside tools. The README says it is mainly a voice interaction entry point that works with large models such as Qwen and DeepSeek.

  • Flash a prebuilt firmware onto a supported board and talk to it by voice
  • Add a custom wake word using the ESP-SR offline wake-up feature
  • Control device features such as LEDs, servos or GPIO through device-side MCP
  • Connect cloud-side MCP tools for smart home control, knowledge search or email, as listed in the README
  • Run a self-hosted server using one of the related server projects listed in the README

Great for

  • Hobbyists who want a voice assistant on a supported ESP32 development board
  • Developers building a custom voice device or adding MCP-controlled hardware
  • Makers who want to experiment with the xiaozhi.me cloud service and its free Qwen real-time model
  • Students learning embedded C++ on real hardware with audio and display peripherals

Not ideal for

  • People without an ESP32-compatible board, since the firmware runs only on that hardware
  • Users who need a finished consumer product with no setup, because the README points beginners to a flashing guide and the build path requires ESP-IDF
  • Teams requiring a specific SDK version below ESP-IDF v6.0.1, since the README says 5.x is no longer supported
Step-by-step guide: how to use XiaoZhiInstall, first run, examples, tips and FAQs
nanobot vs XiaoZhiXiaoZhi vs 小智 (Xiaozhi)

How to get it

  1. 1

    Clone and build from source

    You'll need: ESP-IDF v6.0.1 or later (release/v6.1 recommended) · Cursor or VSCode with the ESP-IDF plugin · Linux is recommended over Windows according to the README

    Clone the repository

    git clone https://github.com/78/xiaozhi-esp32

    Update ESP-IDF submodules after switching SDK revision

    git submodule update --init --recursive

    Clean the project before rebuilding after an SDK change

    idf.py fullclean
  2. 2

    Run it

    • For the easiest start, follow the README's beginner firmware flashing guide instead of building from source
    • If building from source, install ESP-IDF release/v6.1 and source its export.sh
    • Build and flash the firmware to a supported board
    • Connect the board to Wi-Fi through the hotspot or BluFi provisioning method
    • Register at xiaozhi.me to configure the large model and talk to the device
  3. 3

    Get the most out of it

    • Configure the large model through the xiaozhi.me console, as described in the README
    • Create a custom board using the Custom Board Guide in docs/custom-board.md
    • Use device-side and cloud-side MCP to extend what the assistant can control
    • Customize wake words, fonts, emojis and chat backgrounds with the Custom Assets Generator linked in the README
    • Read docs/mcp-usage.md and docs/websocket.md to understand the protocols before building integrations

Downloads

Source code (.zip)main branch · straight from GitHubRelease v2.5.28 files incl. v2.5.2_alientek-atk-dnesp32s3-box.zipOfficial website & docsxiaozhi.me

Strengths

  • Large hardware support list, with 138 board directories and 171 release variants per the README
  • Supports multiple connection options, including Wi-Fi, Ethernet and 4G, plus WebSocket and MQTT+UDP transports
  • Documented developer guides for custom boards, MCP usage and the communication protocols

Trade-offs

  • Building from source requires ESP-IDF v6.0.1 or later and the README warns about specific tag and submodule pitfalls
  • Default setup relies on the official xiaozhi.me server, and the README does not detail self-hosting beyond linking third-party server projects
  • Much of the setup documentation and tutorials are hosted on external sites and in Chinese, so the README alone may not cover every step

How it compares

ProjectStarsTypeLevelUpdatedBest for
xiaozhi-esp32 (this)32.5kAppintermediate5 days agoHobbyists who want a voice assistant on a supported ESP32 development board
xiaozhi-esp32-server11.1kAppadvanced4 days agoOwners of ESP32 voice-assistant hardware who want their own backend
nanobot49.8kAppintermediate4 days agoPeople who want a self-hosted personal assistant they can inspect and customize
cc-switch151kAppbeginner4 days agoDevelopers who use several AI coding agents and switch between API providers often
paperclip110kAppadvanced4 days agoDevelopers already running several AI coding agents who want one place to track them
mempalace60.2kAppintermediate6 days agoDevelopers who use Claude Code or another MCP-capable coding agent and want it to recall past sessions

Stats synced from GitHub. The assessment above was drafted with AI from the project's README on 2026-10-29 and may miss recent changes — check the README before relying on a command. MIT licence: free to use, modify and distribute, including commercially, as long as you keep the copyright notice.